Services/Sync/Server/Archived/0.3/API
Contents
Weave 0.3 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 Basic Object has the following fields:
| Parameter | Default | Max | Description |
| 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. |
| parentid | none | 64 | The id of a parent object in the same collection. This allows for the creation of hierarchical structures (such as folders). |
| modified | time submitted | float (2 decimal places) | The last-modified date, in seconds since 01/01/1970 (see ecma-262). Set by the server. |
| sortindex | none | integer | A sort index to allow for ordered lists/trees. |
| depth | none | tinyint | The depth of the node from the root of the tree. Useful as a sort key for ordered trees. |
| 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. Payload Definitions |
Weave Basic Objects and all data passed into the Weave Server should be utf-8 encoded.
Sample:
{
"id": "B1549145-55CB-4A6B-9526-70D370821BB5",
"parentid": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC",
"modified": "2454725.98283",
"encryption": "",
"encoding": "shift-JIS",
"payload": "{\"encryption\":\"http://server/prefix/version/user/crypto-meta/B1549145-55CB-4A6B-9526-70D370821BB5\", \"data\": \"a89sdmawo58aqlva.8vj2w9fmq2af8vamva98fgqamff...\"}"
}
URL Semantics
Weave URLs follow, for the most part, REST semantics. Request and response bodies are all JSON-encoded.
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 Error Response
The Weave API has a set of 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/0.3/user/username/
Returns a list of collections associated with the account
https://server/0.3/user/username/collection
Returns a list of the WBO ids contained in a collection. This request has additional optional parameters:
| Term | Description |
| parentid | Returns the ids for objects in the collection that are the children of the parent id given. |
| 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. |
| 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 | 'oldest' - Orders by modification date (oldest first) 'newest' - Orders by modification date (newest first) |
https://server/0.3/user/username/collection/id
Returns the WBO in the collection corresponding to the requested id
PUT
https://server/0.3/user/username/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/0.3/user/username/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/0.3/user/username/collection
Deletes the collection and all contents. Additional request parameters may modify the selection of which items to delete:
| Term | Description |
| parentid | Only deletes objects in the collection that are the children of the parent id given. |
| older | Only deletes objects in the collection that have been last modified before the date given. |
| newer | Only deletes objects in the collection that have been last modified since the date given. |
| limit | Sets the maximum number of objects that will be deleted. |
| offset | Skips the first n objects in the defined set. Must be used with the limit parameter. |
| sort | 'oldest' - Orders by modification date (oldest first) 'newest' - Orders by modification date (newest first) |
https://server/0.3/user/username/collection/id
Deletes the WBO at the location given
All delete requests return the timestamp of the action.
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.
