Apps/Sync/Spec2: Difference between revisions

← Older edit

Apps/Sync/Spec2 (view source)

Revision as of 22:46, 14 December 2011

2,785 bytes added , 14 December 2011

→‎Authentication

Ianb

Confirmed users

176

edits

@@ Line 36: / Line 36: @@
 The <tt>id</tt> key must be unique for the type (submitting another key by the same id means that you are overwriting that object).
+You can also have a deleted object, which lives as an object in sync but doesn't have any data:
+    {type: "type_name",
+     id: "unique identifier",
+     expires: timestamp,
+     deleted: true
+    }
 == Requests ==
@@ Line 84: / Line 92: @@
      POST /USER?since=counter3&collection_id=string_id
      ...
+A successful response will be:
+    {object_counters: [counter4, counter5, ...]}
+The counters will correspond to each item that you sent.  ('''Note:''' maybe this should include a timestamp of sorts too?)
 === Conflicts ===
@@ Line 110: / Line 124: @@
 The response may include <tt>until: "counter3"</tt>, which might be newer than the newest item that was returned (this happens when the newest item is not of the type you requested).
+You may also include these same filters on your POST requests; this keeps a conflict from happening even if an object of an excluded type has been added.
 == Server Failure and Backoff ==
@@ Line 130: / Line 146: @@
      {incomplete: true}
+'''Note:''' there's a major problem here where a new assertion could create a new user, and then though the uuid changes etc, it means everything gets uploaded and downloaded from this new user's data.  While this might be okay for the client, it should be noticed and confirmed by the client (as a kind of change of identity).
+= Clients =
+The client algorithm is to get and put updates, storing them locally.  That easy?  Sure!
+== GET ==
+The client needs to keep a record of these values:
+* The <tt>since</tt> counter
+* The <tt>collection_id</tt>
+* The endpoint URL (it's sticky)
+* Authentication
+The <tt>since</tt> counter and the <tt>collection_id</tt> go together to point to where in the stream of updates the client is.  If the collection changes, that counter becomes meaningless, hence the <tt>collection_id</tt> - and when you get a <tt>collection_changed</tt> response you should forget your <tt>since</tt> value.
+Every time you get a response, you update the <tt>since</tt> value if there were updates.  If <tt>until</tt> is set on the response, use that, otherwise use the counter from the last item in <tt>objects</tt>.  If you get no objects, no until, or a 204 No Content respones, then don't change anything.
+You should keep getting stuff so long as the response includes <tt>incomplete: true</tt>.  This might also mean redirects (in <tt>X-Sync-Location</tt>).  Also Retry-After and X-Sync-Poll-Time should inform the speed at which you make requests.
+== POST ==
+Once you've retrieved the values, then you can send your own new values.  You'll send <tt>?since={since}</tt> just like with GET, because you must always incorporate every value before sending your own.  This ensures that anyone who adds to the sync timeline is fully aware of everything preceding.
+The POST results, when successful, also update <tt>since</tt>.  And the POST results when unsuccessful look just like a GET (since you needed to do a GET, right?)
+=== Quarantine ===
+Sometimes you may not understand an object you receive; its type, or the format it is in.  This might be because of corruption, but it might also be because another client has a newer/richer notion of the type than you do.  ('''XXX''': conitnue)