MozillaWiki

Identity/AttachedServices/StorageProtocolZero: Difference between revisions

Page Discussion

Identity/AttachedServices/StorageProtocolZero (view source)

Revision as of 04:21, 27 February 2013

59 bytes added ,  27 February 2013
no edit summary
No edit summary
No edit summary
Line 3: Line 3:
This is a working proposal for the PICL Storage API to store and retrieve simple objects called Basic Storage Objects, which are organized into named collections.  It is based on the [https://docs.services.mozilla.com/storage/apis-2.0.html Mozilla SyncStorge 2.0 API] with some simplifications.
This is a working proposal for the PICL Storage API to store and retrieve simple objects called Basic Storage Objects, which are organized into named collections.  It is based on the [https://docs.services.mozilla.com/storage/apis-2.0.html Mozilla SyncStorge 2.0 API] with some simplifications.


This will *not* be the final protocol used by PICL.  It is an attempt to re-use existing protocol work to enable rapid early iteration.
This will '''not''' be the final protocol used by PICL.  It is an attempt to re-use existing protocol work to enable rapid early iteration.




Line 23: Line 23:
<tr><td>deleted</td><td>false</td><td>bool</td><td>Whether this object is deleted.</td></tr>
<tr><td>deleted</td><td>false</td><td>bool</td><td>Whether this object is deleted.</td></tr>
</table>
</table>


== Collections ==
== Collections ==
Line 29: Line 30:


Collections are created implicitly when a BSO is stored in them for the first time. They continue to exist indefinitely since the BSO records they contain cannot be deleted, only marked for deletion.
Collections are created implicitly when a BSO is stored in them for the first time. They continue to exist indefinitely since the BSO records they contain cannot be deleted, only marked for deletion.


== Version Numbers ==
== Version Numbers ==
Line 53: Line 55:
All data transfer between server and client is utf8-encoded JSON bodies, with content-type of application/json.
All data transfer between server and client is utf8-encoded JSON bodies, with content-type of application/json.


GET https://<server-url>/<userid>/info/collections
=== GET https://<server-url>/<userid>/info/collections ===


Returns a mapping of collection names associated with the account to the last-modified version number for each collection.
Returns a mapping of collection names associated with the account to the last-modified version number for each collection.
Line 59: Line 61:
Example response:
Example response:


{ “version”: 42,    // the current version number for the whole store
    { “version”: 42,    // the current version number for the whole store
 
      “collections”:  { // the last-modified version number for each collection
“collections”:  { // the last-modified version number for each collection
        “tabs”: 42,
 
        “bookmarks”:  38
    “tabs”: 42,
    }}
 
    “bookmarks”:  38
 
}}


Possible HTTP status codes:
Possible HTTP status codes:


        200 OK: everything went fine.
* 200 OK: everything went fine.
 
* 304 Not Modified: the current version number is less than or equal to the value specified in the X-If-Modified-Since-Version header.
    304 Not Modified: the current version number is less than or equal to the value specified in the X-If-Modified-Since-Version header.
 




GET https://<server-url>/<userid>/storage/<collection>
=== GET https://<server-url>/<userid>/storage/<collection> ===


Returns a list of all BSOs in the collection, or all those matching the specified query parameters.
Returns a list of all BSOs in the collection, or all those matching the specified query parameters.
Line 83: Line 79:
Query parameters:
Query parameters:


        ids: a comma-separated list of ids. Only objects whose id is in this list will be returned. A maximum of 100 ids may be provided.
* ids: a comma-separated list of ids. Only objects whose id is in this list will be returned. A maximum of 100 ids may be provided.
        newer: a version number. Only objects whose last-modified version number is strictly greater than this value will be returned.
* newer: a version number. Only objects whose last-modified version number is strictly greater than this value will be returned.




Example response:
Example response:


{ “version”:  42,    // the last-modified version number for this collection
    { “version”:  42,    // the last-modified version number for this collection
 
      “items”:  [       // the BSOs that match this query
“items”:  [           // the BSOs that match this query
        { “id”: “mybookmark”, “version”: 17, … },
 
        { “id”: “abookmark”, “version”: 42, … },
    { “id”: “mybookmark”, “version”: 17, … },
    ]}
 
    { “id”: “abookmark”, “version”: 42, … },
 
]}


Possible HTTP status codes:
Possible HTTP status codes:


    200 OK: success was had
* 200 OK: success was had
    304 Not Modified: the last-modified version number of the collection is less than or equal to the value in the X-If-Modified-Since-Version header.
* 304 Not Modified: the last-modified version number of the collection is less than or equal to the value in the X-If-Modified-Since-Version header.
    400 Bad Request: something was wrong with the request, e.g. too many ids were included in the query parameter.
* 400 Bad Request: something was wrong with the request, e.g. too many ids were included in the query parameter.
    404 Not Found: the user has no such collection.
* 404 Not Found: the user has no such collection.
 




POST https://<server-url>/<userid>/storage/<collection>
=== POST https://<server-url>/<userid>/storage/<collection> ===


Creates or updates BSOs within a collection, and responds with the new version number for that collection.  A maximum of 100 BSOs may be included in the request.
Creates or updates BSOs within a collection, and responds with the new version number for that collection.  A maximum of 100 BSOs may be included in the request.
Line 114: Line 105:
The request body must be a JSON array of BSO objects, which will be iterated over.  Any BSOs that already exist will have their data updated with the provided fields; BSOs that do not exist will be created.  Deletion is achieved by setting the “deleted” field to true.
The request body must be a JSON array of BSO objects, which will be iterated over.  Any BSOs that already exist will have their data updated with the provided fields; BSOs that do not exist will be created.  Deletion is achieved by setting the “deleted” field to true.


    Example response:
Example response:


{ “version”: 42 }
    { “version”: 42 }


Possible HTTP status codes:
Possible HTTP status codes:


    200 OK: the request completed successfully, creating the collection if necessary.
* 200 OK: the request completed successfully, creating the collection if necessary.
    400 Bad Request: something was wrong with the request, e.g. too many BSOs were included in the request.
* 400 Bad Request: something was wrong with the request, e.g. too many BSOs were included in the request.
    412 Precondition Failed: the last-modified version number of the collection is greater than the value in the X-If-Unmodified-Since-Version header.
* 412 Precondition Failed: the last-modified version number of the collection is greater than the value in the X-If-Unmodified-Since-Version header.




Request Headers
== Request Headers ==


X-If-Modified-Since-Version
=== X-If-Modified-Since-Version ===


This header may be added to any GET request, set to a version number. If the last-modified version of the target resource is less than or equal to the version number given, then a 304 Not Modified response will be returned and re-transmission of the unchanged data will be avoided.
This header may be added to any GET request, set to a version number. If the last-modified version of the target resource is less than or equal to the version number given, then a 304 Not Modified response will be returned and re-transmission of the unchanged data will be avoided.
Line 135: Line 126:
If the value of this header is not a valid positive integer, or if the X-If-Unmodified-Since-Version header is also present, then a 400 Bad Request response will be returned.
If the value of this header is not a valid positive integer, or if the X-If-Unmodified-Since-Version header is also present, then a 400 Bad Request response will be returned.


X-If-Unmodified-Since-Version
=== X-If-Unmodified-Since-Version ===


This header may be added to any request to a collection or item, set to a version number. If the last-modified version of the target resource is greater than the version number given, the request will fail with a 412 Precondition Failed response.
This header may be added to any request to a collection or item, set to a version number. If the last-modified version of the target resource is greater than the version number given, the request will fail with a 412 Precondition Failed response.
Line 142: Line 133:


If the value of this header is not a valid positive integer, or if the X-If-Modified-Since-Version header is also present, then a 400 Bad Request response will be returned.
If the value of this header is not a valid positive integer, or if the X-If-Modified-Since-Version header is also present, then a 400 Bad Request response will be returned.
Response Headers
 
X-Last-Modified-Version
 
== Response Headers ==
 
=== X-Last-Modified-Version ===


This header gives the last-modified version number of the target resource as seen during processing of the request, and will be included in all success responses (200, 201, 204).
This header gives the last-modified version number of the target resource as seen during processing of the request, and will be included in all success responses (200, 201, 204).
Rfkelly
Confirmed users
358

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/530842"