Services/Sync/Server/API/Storage/1.1: Difference between revisions

From MozillaWiki
< Services‎ | Sync‎ | Server‎ | API
Jump to navigation Jump to search
m (Created page with '= Weave 1.1 API = Release Date: TBD = Weave Basic Object (WBO) = A Weave Basic Object is the generic wrapper around all items passed into and out of the Weave server. The Weave …')
 
(blank page since content on docs.services.m.c)
 
(24 intermediate revisions by 5 users not shown)
Line 1: Line 1:
= Weave 1.1 API =
{{Warning| This page is now located at http://docs.services.mozilla.com/storage/}}
Release Date: TBD
 
= Weave Basic Object (WBO) =
A Weave Basic Object is the generic wrapper around all items passed into and out of the Weave server. The Weave Basic Object has the following fields:
 
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
| style="background-color: #efefef;" | '''Parameter'''
| style="background-color: #efefef; width: 100px" | '''Default'''
| '''Max'''
| '''Description'''
|- valign="top"
| id
| required
| 64
| An identifying string. For a user, the id must be unique for a WBO within a collection, though objects in different collections may have the same ID. Ids should be ASCII and not contain commas.
|- valign="top"
| parentid
| none
| 64
| The id of a parent object in the same collection. This allows for the creation of hierarchical structures (such as folders).
|- valign="top"
| predecessorid
| none
| 64
| The id of a predecessor in the same collection. This allows for the creation of linked-list-esque structures.
|- valign="top"
| modified
| time submitted
| float (2 decimal places)
| The last-modified date, in seconds since 01/01/1970 (see [http://www.ecma-international.org/publications/standards/Ecma-262.htm ecma-262]). Set by the server.
|- valign="top"
| sortindex
| none
| integer
| An integer indicting the relative importance of this item in the collection.
|- valign="top"
| payload
| none
| 256K
| A string containing a JSON structure encapsulating the data of the record. This structure is defined separately for each WBO type. Parts of the structure may be encrypted, in which case the structure should also specify a record for decryption.
|}
 
Weave Basic Objects and all data passed into the Weave Server should be utf-8 encoded.
 
=== Sample: ===
<pre>
{
"id": "B1549145-55CB-4A6B-9526-70D370821BB5",
"parentid": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC",
"modified": "2454725.98",
"payload": "{\"encryption\":\"http://server/prefix/version/user/crypto-meta/B1549145-55CB-4A6B-9526-70D370821BB5\", \"data\": \"a89sdmawo58aqlva.8vj2w9fmq2af8vamva98fgqamff...\"}"
}
</pre>
 
= Collections =
 
Each WBO is assigned to a collection with other related WBOs. Collection names may only contain alphanumeric characters, period, underscore and hyphen. Collections supported at this time are:
 
* bookmarks
* history
* forms
* prefs
* tabs
* passwords
 
Additionally, the following collections are supported for internal Weave client use:
 
* clients
* crypto
* keys
* meta
 
= URL Semantics =
 
Weave URLs follow, for the most part, REST semantics. Request and response bodies are all JSON-encoded.
 
The URL for Weave Storage requests is structured as follows:
 
https://<server name>/<api pathname>/<version>/<username>/<further instruction>
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
| '''Component'''
| '''Mozilla Default'''
| '''Description'''
|- valign="top"
| server name
| (defined by user account node)
| the hostname of the server
|- valign="top"
| pathname
| (none)
| the prefix associated with the service on the box
|- valign="top"
| version
| 1.0
| The API version. May be integer or decimal
|- valign="top"
| username
| (none)
| the name of the object (user) to be manipulated
|- valign="top"
| further instruction
| (none)
| The additional function information as defined in the paths below
|}
 
Weave uses HTTP basic auth (over SSL, so as to maintain password security). If the auth username does not match the username in the path, the server will issue an [https://wiki.mozilla.org/Labs/Weave/1.0/ResponseCodes Error Response]
 
The Weave API has a set of  [https://wiki.mozilla.org/Labs/Weave/1.0/ResponseCodes Weave Response Codes] to cover errors in the request or on the server side. The format of a successful response is defined in the appropriate request method section.
 
== GET ==
 
'''https://''server''/''pathname''/''version''/''username''/info/collections '''
 
Returns a hash of collections associated with the account, along with the last modified timestamp for each collection.
 
'''https://''server''/''pathname''/''version''/''username''/info/collections_usage '''
 
Returns a hash of collections associated with the account, along with the data volume used for each.
 
'''https://''server''/''pathname''/''version''/''username''/info/collection_counts '''
 
Returns a hash of collections associated with the account, along with the total number of items for each collection.
 
'''https://''server''/''version''/''username''/info/quota '''
 
Returns a tuple containing the user's current usage (in K) and quota.
 
'''https://''server''/''pathname''/''version''/''username''/storage/''collection'' '''
 
Returns a list of the WBO ids contained in a collection. This request has additional optional parameters:
 
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
| '''Term'''
| '''Description'''
|- valign="top"
| ids
| Returns the ids for objects in the collection that are in the provided comma-separated list.
|- valign="top"
| predecessorid
| Returns the ids for objects in the collection that are directly preceded by the id given. Usually only returns one result.
|- valign="top"
| parentid
| Returns the ids for objects in the collection that are the children of the parent id given.
|- valign="top"
| older
| Returns only ids for objects in the collection that have been last modified before the date given.
|- valign="top"
| newer
| Returns only ids for objects in the collection that have been last modified since the date given.
|- valign="top"
| full
| If defined, returns the full WBO, rather than just the id.
|- valign="top"
| index_above
| If defined, only returns items with a higher sortindex than the value specified.
|- valign="top"
| index_below
| If defined, only returns items with a lower sortindex than the value specified.
|- valign="top"
| limit
| Sets the maximum number of ids that will be returned.
|- valign="top"
| offset
| Skips the first n ids. For use with the limit parameter (required) to paginate through a result set.
|- valign="top"
| sort
| 'oldest' - Orders by modification date (oldest first)<br>
'newest' - Orders by modification date (newest first)<br>
'index' - Orders by the sortindex descending (highest weight first)<br>
|- valign="top"
| ttl
| none (optional)
| integer
| The number of seconds to keep this record. After that time, this item will not be returned.
|}
 
 
'''https://''server''/''pathname''/''version''/''username''/storage/''collection''/''id'' '''
 
Returns the WBO in the collection corresponding to the requested id
 
=== Alternate Output Formats ===
 
Two alternate output formats are available for multiple record GET requests. They are triggered by the presence of the appropriate format in the Accept header (with application/whoisi taking precedence)
 
*application/whoisi: each record consists of a 32-bit integer, defining the length of the record, followed by the json record for a wbo
 
*application/newlines: each record is a separate json object on its own line. Newlines in the body of the json object are replaced by '\u000a'
 
== PUT ==
 
'''https://''server''/''pathname''/''version''/''username''/storage/''collection''/''id'' '''
 
Adds the WBO defined in the request body to the collection. If the WBO does not contain a payload, it will only update the provided metadata fields on an already defined object.
 
The server will return the timestamp associated with the modification.
 
== POST ==
 
'''https://''server''/''pathname''/''version''/''username''/storage/''collection'' '''
 
Takes an array of WBOs in the request body and iterates over them, effectively doing a series of atomic PUTs with the same timestamp.
 
Returns a hash of successful and unsuccessful saves, including guidance as to possible errors:
 
<pre>
{"modified":1233702554.25,"success":["{GXS58IDC}12","{GXS58IDC}13","{GXS58IDC}15","{GXS58IDC}16","{GXS58IDC}18","{GXS58IDC}19"],"failed":{"{GXS58IDC}11":["invalid parentid"],"{GXS58IDC}14":["invalid parentid"],"{GXS58IDC}17":["invalid parentid"],"{GXS58IDC}20":["invalid parentid"]}}
</pre>
 
'''https://''server''/''pathname''/''version''/''username''/storage '''
 
Takes an array of WBOs in the request body and iterates over them, effectively doing a series of atomic PUTs with the same timestamp. Each wbo must have a collection specified.
 
Returns a hash for each collection of successful and unsuccessful saves, including guidance as to possible errors:
 
<pre>
{
  "collection1":
    {"success":["{GXS58IDC}12"],
    "failed":{"{GXS58IDC}11":["invalid id"]}},
  "collection2":
    {"success": ["{GXS58IDC}13","{GXS58IDC}15","{GXS58IDC}16","{GXS58IDC}18","{GXS58IDC}19"],
    "failed":{"{GXS58IDC}11":["invalid id"],"{GXS58IDC}14":["payload too long"]}}}
</pre>
 
== DELETE ==
 
'''https://''server''/''pathname''/''version''/''username''/storage/''collection'' '''
 
Deletes the collection and all contents. Additional request parameters may modify the selection of which items to delete:
 
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
| '''Term'''
| '''Description'''
|- valign="top"
| ids
| Deletes the ids for objects in the collection that are in the provided comma-separated list.
|- valign="top"
| parentid
| Only deletes objects in the collection that are the children of the parent id given.
|- valign="top"
| older
| Only deletes objects in the collection that have been last modified before the date given.
|- valign="top"
| newer
| Only deletes objects in the collection that have been last modified since the date given.
|- valign="top"
| limit
| Sets the maximum number of objects that will be deleted.
|- valign="top"
| offset
| Skips the first n objects in the defined set. Must be used with the limit parameter. [This function is not currently operational in the mysql implementation]
|- valign="top"
| sort
| 'oldest' - Orders by modification date (oldest first)<br>
'newest' - Orders by modification date (newest first)<br>
'index' - Orders by the sortindex (ordered lists)<br>
'depthindex' - Orders by depth, then by sortindex (ordered trees)
|}
 
 
'''https://''server''/''pathname''/''version''/''username''/storage/''collection''/''id'' '''
 
Deletes the WBO at the location given
 
All delete requests return the timestamp of the action.
 
 
'''https://''server''/''pathname''/''version''/''username''/storage
 
Deletes all records for the user. Will return a precondition error unless an X-Confirm-Delete header is included.
 
All delete requests return the timestamp of the action.
 
= General Weave Headers =
 
== X-Weave-Backoff ==
 
Indicates that the server is under heavy load or has suffered a failure and the client should not try again for the specified number of seconds (usually 1800)
 
== X-If-Unmodified-Since ==
 
On any write transaction (PUT, POST, DELETE), this header may be added to the request, set to a timestamp. If the collection to be acted on has been modified since the timestamp given, the request will fail.
 
== X-Weave-Alert ==
 
This header may be sent back from any transaction, and contains potential warning messages, information, or other alerts. The contents are intended to be human-readable.
 
 
== X-Weave-Timestamp ==
 
This header will be sent back with all requests, indicating the current timestamp on the server. If the request was a PUT or POST, this will also be the modification date of any WBOs submitted or modified.
 
== X-Weave-Records ==
If supported by the db, this header will return the number of records total in the request body of any multiple-record GET request.

Latest revision as of 20:45, 15 August 2011

Warning signWarning: This page is now located at http://docs.services.mozilla.com/storage/
Retrieved from "https://wiki.allizom.org/index.php?title=Services/Sync/Server/API/Storage/1.1&oldid=339767"