Confirmed users
358
edits
Identity/AttachedServices/StorageServerProtocol: Difference between revisions
Jump to navigation
Jump to search
Identity/AttachedServices/StorageServerProtocol (view source)
Revision as of 06:31, 14 May 2013
, 14 May 2013no edit summary
(Created page with "== Summary == This is a working proposal for the PiCL Storage API, to implement the concepts described in Identity/CryptoIdeas/04-Delta-Sync. It's a work in progress that wi...") |
No edit summary |
||
| Line 81: | Line 81: | ||
< "version": <version id for this collection> | < "version": <version id for this collection> | ||
< } | < } | ||
=== GET <base-url>/<collection>/<version> === | |||
Get the contents of a specific version of a specific collection. In the simplest case, we GET the full contents like so: | |||
> GET <base-url>/<collection>/<version> | |||
> Authorization: <hawk auth parameters> | |||
. | |||
< 200 OK | |||
< Content-Type: application/json | |||
< { | |||
< "items": { | |||
< "key1": "value1", | |||
< "key2": "value2", | |||
< <..etc..> | |||
< } | |||
< } | |||
However, clients will usually want to request a delta from a previous version. They can do this by specifying the "from" parameter. New or updated keys are represented with their value, while deleted keys are represented with a value of null. Like so: | |||
> GET <base-url>/<collection>/<version>?from=<previous version> | |||
> Authorization: <hawk auth parameters> | |||
. | |||
< 200 OK | |||
< Content-Type: application/json | |||
< { | |||
< "items": { | |||
< "key1": "value1", // a key that was updated | |||
< "key2": null // a key that was deleted | |||
< } | |||
< } | |||
To allow reliable transfer of a large number of items, both client and server may choose to paginate responses to this query. | |||
The client may specify "first" as the key at which to (lexicographically) start the listing, and "last" as the key at which to stop the listing. It may also specify an integer "limit" to restrict the total number of keys sent at once. The server may enforce a default value and/or upper-bound on "limit". | |||
If the set of items is truncated, the server will send the response argument "next" to give the next available key in iteration order. The client should make another request setting "first" equal to the provided value of "next" in order to fetch additional items. | |||
As an example, suppose that the client requests at most two items per response, and the collection contains items "key1", "key2" and "key3". It would would need to fetch them in two batches like so: | |||
> GET <base-url>/<collection>/<version>?limit=2 | |||
> Authorization: <hawk auth parameters> | |||
. | |||
< 200 OK | |||
< Content-Type: application/json | |||
< { | |||
< "next": "key3", | |||
< "items": { | |||
< "key1": "value1", | |||
< "key2": "value2" | |||
< } | |||
< } | |||
. | |||
. | |||
> GET <base-url>/<collection>/<version>?first=key3&limit=2 | |||
> Authorization: <hawk auth parameters> | |||
. | |||
< 200 OK | |||
< Content-Type: application/json | |||
< { | |||
< "items": { | |||
< "key3": "value3" | |||
< } | |||
< } | |||
There are several error cases that need to be distinguished, possibly by HTTP status code or possibly by some information in the error response body: | |||
* The requested version is not known or no longer present on the server | |||
* We can't generate a delta from the requested "from" version to the request version | |||
* The requested "from" version is invalid (e.g. due to lost writes during a rollback) | |||