Confirmed users
176
edits
Apps/Sync/Spec2: Difference between revisions
Jump to navigation
Jump to search
no edit summary
mNo edit summary |
No edit summary |
||
| Line 15: | Line 15: | ||
For "known" datatypes the sync server ensures the integrity of data, according to the most up-to-date notion of correctness for the data type. As such the sync server must be updated frequently, but clients will be protected from some other rogue clients. ('''Note:''' not sure if this is a practical expectation?) | For "known" datatypes the sync server ensures the integrity of data, according to the most up-to-date notion of correctness for the data type. As such the sync server must be updated frequently, but clients will be protected from some other rogue clients. ('''Note:''' not sure if this is a practical expectation?) | ||
= Protocol = | |||
We'll go out-of-order time-wise, and forget about authentication for now. | We'll go out-of-order time-wise, and forget about authentication for now. | ||
| Line 21: | Line 21: | ||
Everything happens at a single URL endpoint, we'll call it <tt>/USER</tt> | Everything happens at a single URL endpoint, we'll call it <tt>/USER</tt> | ||
== Objects == | |||
Each object looks like this: | Each object looks like this: | ||
| Line 37: | Line 37: | ||
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). | 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). | ||
== Requests == | |||
You can retrieve and send updates. The first time there's not a lot to do, you can just do: | You can retrieve and send updates. The first time there's not a lot to do, you can just do: | ||
| Line 55: | Line 55: | ||
GET /USER?since=counter2&collection_id=string_id | GET /USER?since=counter2&collection_id=string_id | ||
You get the objects back, but with no <tt>collection_id</tt> (you already know it!) | You get the objects back, but with no <tt>collection_id</tt> (you already know it!) If there have been no changes you get back a <tt>204 No Content</tt> response. | ||
If <tt>objects</tt> is empty, you start with a counter <tt>0</tt>. | If <tt>objects</tt> is empty, you start with a counter <tt>0</tt>. | ||
| Line 85: | Line 85: | ||
... | ... | ||
=== Conflicts === | |||
We do not resolve conflicts as part of sync, and you are strongly recommended not to burden your users with conflicts as part of your sync schedule. | We do not resolve conflicts as part of sync, and you are strongly recommended not to burden your users with conflicts as part of your sync schedule. | ||
| Line 93: | Line 93: | ||
If you can't automatically resolve the conflicts you must incorporate all your conflicting edits into a new object, and when the user at some point can attend to the object you can show them the conflicts and ask for a resolution, putting the resolved object onto the server. | If you can't automatically resolve the conflicts you must incorporate all your conflicting edits into a new object, and when the user at some point can attend to the object you can show them the conflicts and ask for a resolution, putting the resolved object onto the server. | ||
=== Partial Results === | |||
You may not want too many results. In this case add to your GET requests: | You may not want too many results. In this case add to your GET requests: | ||
| Line 101: | Line 101: | ||
This will return at most 10 items. The server may also choose not to return a full set of items. In either case the result object will have <tt>incomplete: true</tt>. You can make another request and get more items. | This will return at most 10 items. The server may also choose not to return a full set of items. In either case the result object will have <tt>incomplete: true</tt>. You can make another request and get more items. | ||
=== Typed Results === | |||
Sometimes you only care about a subset of objects. The stream can have any number of types of objects, and while a full client may handle everything a more limited client may not care about some items. In this case do: | Sometimes you only care about a subset of objects. The stream can have any number of types of objects, and while a full client may handle everything a more limited client may not care about some items. In this case do: | ||
| Line 110: | Line 110: | ||
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). | 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). | ||
== Server Failure and Backoff == | |||
The server may return a 503 response, with a <tt>Retry-After</tt> value. In any request it may also reply with <tt>X-Sync-Poll-Time</tt>, which is appended to a successful request but requests that you not make another request for the given time (in seconds). | |||
== Authentication == | |||
Each request has to have authentication. The authentication uses BrowserID. The first request you need send the browserid assertion. You send this like: | |||
Authorization: BrowserID assertion=XXX | |||
Note that these assertions are only valid for a short amount of time, so expect a response like: | |||
X-Set-Authorization: NewAuthType value | |||
You should use this for the <tt>Authorization</tt> header after this. It may get updated (typically to refresh an expiration time). | |||
On the first request you don't actually know the endpoint to talk to. In any request you may get a <tt>X-Sync-Location</tt> response ('''Note:''' <tt>Content-Location</tt>?). In the first request you ask the root server (at some well-known URL). A server that does not wish to respond except for this redirect may just give: | |||
{incomplete: true} | |||