This document describes the Sync Server Storage API, version 1.1. It has been replaced by SyncStorage API v1.5.
The Storage server provides web services that can be used to store and retrieve Weave Basic Objects or WBOs organized into collections.
A Weave Basic Object (WBO) is the generic JSON wrapper around all items passed into and out of the storage server. Like all JSON, Weave Basic Objects need to be UTF-8 encoded. WBOs have the following fields:
Parameter |
Default |
Type/Max |
Description |
|---|---|---|---|
id |
required |
string 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. This should be exactly 12 characters from the base64url alphabet. While this isn’t enforced by the server, the Firefox client expects this in most cases. |
modified |
time submitted |
float 2 decimal places |
|
sortindex |
none |
integer |
An integer indicating the relative importance of this item in the collection. |
payload |
none |
string 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. |
ttl |
none |
integer |
The number of seconds to keep this record. After that time, this item will not be returned. |
parentid [1] |
none |
string 64 |
The id of a parent object in the same collection. This allows for the creation of hierarchical structures (such as folders). |
predecessorid [1] |
none |
string 64 |
The id of a predecessor in the same collection. This allows for the creation of linked-list-esque structures. |
Sample:
{
"id":"-F_Szdjg3GzY",
"modified":1278109839.96,
"sortindex":140,
"payload":"{\"ciphertext\":\"e2zLWJYX\/iTw3WXQqffo00kuuut0Sk3G7erqXD8c65S5QfB85rqolFAU0r72GbbLkS7ZBpcpmAvX6LckEBBhQPyMt7lJzfwCUxIN\/uCTpwlf9MvioGX0d4uk3G8h1YZvrEs45hWngKKf7dTqOxaJ6kGp507A6AvCUVuT7jzG70fvTCIFyemV+Rn80rgzHHDlVy4FYti6tDkmhx8t6OMnH9o\/ax\/3B2cM+6J2Frj6Q83OEW\/QBC8Q6\/XHgtJJlFi6fKWrG+XtFxS2\/AazbkAMWgPfhZvIGVwkM2HeZtiuRLM=\",\"IV\":\"GluQHjEH65G0gPk\/d\/OGmg==\",\"hmac\":\"c550f20a784cab566f8b2223e546c3abbd52e2709e74e4e9902faad8611aa289\"}"
}
Each WBO is assigned to a collection with other related WBOs. Collection names may only contain alphanumeric characters, period, underscore and hyphen. Default Mozilla collections are:
bookmarks
history
forms
prefs
tabs
passwords
Additionally, the following collections are supported for internal storage client use:
clients
crypto
keys
meta
Storage 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>
Component |
Mozilla Default |
Description |
|---|---|---|
server name |
defined by user account |
the hostname of the server |
pathname |
(none) |
the prefix associated with the service on the box |
version |
1.1 |
The API version. |
username |
(none) |
the name of the object (user) to be manipulated |
further instruction |
(none) |
The additional function information as defined in the paths below |
Certain functions use 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 Error Response.
The User API has a set of 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.
GET https://server/pathname/version/username/info/collection_usage
Returns a hash of collections associated with the account, along with the data volume used for each (in KB).
GET https://server/pathname/version/username/info/collection_counts
Returns a hash of collections associated with the account, along with the total number of items in each collection.
GET https://server/pathname/version/username/info/quota
Returns a list containing the user’s current usage and quota (in KB). The second value will be null if no quota is defined.
GET https://server/pathname/version/username/storage/collection
Returns a list of the WBO ids contained in a collection. This request has additional optional parameters:
ids: returns the ids for objects in the collection that are in the provided comma-separated list.
predecessorid: returns the ids for objects in the collection that are directly preceded by the id given. Usually only returns one result. [4]
parentid: returns the ids for objects in the collection that are the children of the parent id given. [4]
older: returns only ids for objects in the collection that have been last modified before the date given.
newer: returns only ids for objects in the collection that have been last modified since the date given.
full: if defined, returns the full WBO, rather than just the id.
index_above: if defined, only returns items with a higher sortindex than the value specified.
index_below: if defined, only returns items with a lower sortindex than the value specified.
limit: sets the maximum number of ids that will be returned.
offset: skips the first n ids. For use with the limit parameter (required) to paginate through a result set.
sort: sorts the output.
‘oldest’ - Orders by modification date (oldest first)
‘newest’ - Orders by modification date (newest first)
‘index’ - Orders by the sortindex descending (highest weight first)
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’
GET https://server/pathname/version/username/storage/collection/id
Returns the WBO in the collection corresponding to the requested id
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:
{"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"]}}
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:
ids: deletes the ids for objects in the collection that are in the provided comma-separated list.
parentid: only deletes objects in the collection that are the children of the parent id given. [4]
older: only deletes objects in the collection that have been last modified before the date given. [4]
newer: only deletes objects in the collection that have been last modified since the date given. [4]
limit: sets the maximum number of objects that will be deleted. [4]
offset: skips the first n objects in the defined set. Must be used with the limit parameter. [5]
sort: sorts before deleting [4]
‘oldest’ - Orders by modification date (oldest first)
‘newest’ - Orders by modification date (newest first)
‘index’ - Orders by the sortindex (ordered lists)
DELETE https://server/pathname/version/username/storage/collection/id
Deletes the WBO at the location given
DELETE 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.
Retry-After
When sent together with an HTTP 503 status code, it signifies that the server is undergoing maintenance. The client should not attempt another sync for the number of seconds specified in the header value.
X-Weave-Backoff
Indicates that the server is under heavy load and the client should not trigger another sync for the number of seconds specified in the header value (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 in decimal seconds. If the collection to be acted on has been modified since the provided timestamp, the request will fail with an HTTP 412 Precondition Failed status.
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.
200
The request was processed successfully.
400
The request itself or the data supplied along with the request is invalid. The response contains a numeric code indicating the reason for why the request was rejected. See Response codes for a list of valid response codes.
401
The username and password are invalid on this node. This may either be caused by a node reassignment or by a password change. The client should check with the auth server whether the user’s node has changed. If it has changed, the current sync is to be aborted and should be retried against the new node. If the node hasn’t changed, the user’s password was changed.
404
The requested resource could not be found. This may be returned for GET and DELETE requests, for non-existent records and empty collections.
503
Indicates, in conjunction with the Retry-After header, that the server is undergoing maintenance. The client should not attempt another sync for the number of seconds specified in the header value. The response body may contain a JSON string describing the server’s status or error.