Identity/AttachedServices/StorageServerProtocol: Difference between revisions

Jump to navigation Jump to search

Identity/AttachedServices/StorageServerProtocol (view source)

Revision as of 06:39, 14 May 2013

622 bytes removed ,  14 May 2013
no edit summary
No edit summary
No edit summary
Line 116: Line 116:
To allow reliable transfer of a large number of items, both client and server may choose to paginate responses to this query.
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".
The client may specify "first" as the key at which to (lexicographically) start the listing, and "upto" 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.
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.
Line 148: Line 148:




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:
XXX TODO: 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
* 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
* We can't generate a delta from the specified "from" version to the request version
* The requested "from" version is invalid (e.g. due to lost writes during a rollback)
* The specified "from" version is invalid (e.g. due to lost writes during a rollback)
 




Line 171: Line 170:
     .
     .
     <  201 Created
     <  201 Created


However, clients will usually want to send just the changes 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:
However, clients will usually want to send just the changes 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:
Line 185: Line 185:
     <  201 Created
     <  201 Created


To guard against intermittent or unreliable connections, the client can also send data in batches.  It specifies the  The server will spool all the incoming items until the


To guard against intermittent or unreliable connections, the client can also send data in batches.  It can specify the argument "first" to indicate a key offset at which this batch begins, and the argument "upto" to specify a key offset at which this batch ends.  The server will spool all the incoming items until it sees a batch with no "upto" argument, then create the new version as an atomic unit.


As an example, here is how the client might create a new version by sending items one at a time:


     >  GET <base-url>/<collection>/<version>?from=<previous version>
     >  POST <base-url>/<collection>/<version>?upto=key2
     >  Authorization:  <hawk auth parameters>
     >  Authorization:  <hawk auth parameters>
    >  {
    >  "items": {
    >    "key1": value1"
    >  }
    >  }
    .
    < 
     .
     .
     <  200 OK
     .
    <  Content-Type: application/json
     >  POST <base-url>/<collection>/<version>?start=key2&upto=key3
    <  {
    <  "items": {
    <    "key1": "value1",  // a new or modified key
    <    "key2": null,      // a deleted key
    <    <..etc..>
    <  }
    <  }
 
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>
     >  Authorization:  <hawk auth parameters>
    >  {
    >  "items": {
    >    "key2": "value2"
    >  }
    >  }
     .
     .
     <  200 OK
     <   
    <  Content-Type: application/json
    <  {
    <  "next": "key3",
    <  "items": {
    <    "key1": "value1",
    <    "key2": "value2"
    <  }
    <  }
     .
     .
     .
     .
     >  GET <base-url>/<collection>/<version>?first=key3&limit=2
     >  POST <base-url>/<collection>/<version>?start=key3
     >  Authorization:  <hawk auth parameters>
     >  Authorization:  <hawk auth parameters>
    >  {
    >  "items": {
    >    "key3": "value3"
    >  }
    >  }
     .
     .
     <  200 OK
     <  201 Created
    <  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:
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
* There was a conflicting write, so you can no longer create the requested version
* We can't generate a delta from the requested "from" version to the request version
* The requested version is invalid, e.g. wrong sequence number
* The requested "from" version is invalid (e.g. due to lost writes during a rollback)
* The specified "from" version is too old, so we can't use it as the start point of a delta
* The specified "from" version is invalid (e.g. due to lost writes during a rollback)
* The provided batches had holes, or were otherwise invalid
* The server forgot a previous batch and you'll have to start again
Rfkelly
Confirmed users
358

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/655603"

Navigation menu