Services/Sync/Server/Archived/0.3/API

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.

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

Term	Description
server	The name of the Weave server.
prefix	Any added path prefix that defines the Weave namespace on that server.
version	The Weave API version.
user	The userid of the Weave user.
collection	A defined grouping of objects into a set. All basic objects will be a member of one collection, and it will be the access point for those objects.
id	The Weave Basic Object id.

Authentication credentials can be checked at:

https://server/prefix/version/user/

All Protocols: Returns 1.

A WBO will always be accessible at the following URL. All URLs will have REST semantics:

https://server/prefix/version/user/collection/id

GET: Retrieve the object.
PUT: Add/update the object (if no id is provided in the json object, it will use the id in the URL). Returns the modified timestamp.
DELETE: Delete the object.

Batch processing can be done with:

https://server/prefix/version/user/collection

GET: Returns a list of ids associated with the collection.
POST: Takes a JSON array of WBOs and adds/updates them within the collection. Identical to doing a set of PUTs over /id urls. Returns a list of successfully stored objects (with modified timestamps) and failed ones.
DELETE: Deletes all objects in this collection (may be further refined by additional parameters below).

Note that a POST response will return a 200 even if some or all of the objects are invalid. The body will contain lists of successful and failed individual objects.

If a wbo is submitted without a payload, the server will assume that the object contains metadata to be updated and will not touch fields that are not contained in the wbo object.

Optional GET and DELETE parameters:

Term	Description
parentid	Returns the objects in the collection that are the children of the parent id given.
modified	Returns only objects in the collection that have been modified since the date given, ordered by earliest timestamp.
full	If defined, returns the full objects, rather than a group of ids. GET only
limit	Caps the number of objects that will be returned.
sort	'oldest' - Orders by modification date (oldest first) 'newest' - Orders by modification date (newest first) 'index' - Orders by the sortindex (ordered lists) 'depthindex' - Orders by depth, then by sortindex (ordered trees)
offset	Skips the first n objects, for use with the limit parameter

Response Codes

The API uses the standard Weave Response Codes

Payloads

Payloads are a hash with a required "type" key that defines the object type of the payload. Other keys will be required based on this type.

Here are some defined Payload Structures:

Bookmarks

(needs defining)

History

(needs defining)

Private Key

Public Key payloads must be unencrypted. Note that the key itself is still passphrase protected.

Parameter	Default	Description
key_data	required	The private key, passphrase encrypted.
public_key	required	The URI to the public key associated with this private key.

Sample

  "payload": 
  {
    "type": "private_key",
    "key_data": "nviuwc023nd210o3idn120x283cm...",
    "public_key": "A24349145-5AB-2YX-9526"
  }

Public Key

Public Key objects must be unencrypted.

Parameter	Default	Description
key_data	required	The public key
private_key	required	The URI to the private key associated with this private key.

Sample

  "payload": 
  {
    "type": "public_key",
    "key_data": "nviuwc023nd210o3idn120x283cm...",
    "private_key": "B24349145-5AB-2YX-9526"
  }

Cryptometa

Cryptometa objects must be unencrypted.

Parameter	Default	Description
algorithm	required	A hash, containing a "name" key and associated value, and any additional data required for the algorithm, such as "salt" or "iv".
keyring	empty	A hash in which the keys are URLs to publickey WERs and the values are the encryption string used with that key to encrypt this record. The keys may be fully qualified URLs, or relative to the id level (thus, just the id is acceptable)

Sample

  "payload": 
  {
    "type": "cryptometa",
    "algorithm": 
    {
      "name": "aes-256-cbc",
      "salt": "234imasd9f8w23m7",
      "iv": "2w3kmv9821maz985"
    }
    "keyring": 
    {
	  "B24349145-5AB-2YX-9526": "m29f2mnvwiecvnw0ev...",
    }
  }