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	Description
type	required	The type of object contained in the WBO payload. Each type has a defined structure associated with it, beginning with "object". Valid object subtypes, if used, are "cryptowrapper" (whch should be used for all WBOs that have an encrypted payload) or the object type as defined in the payload (optional). Types are hierarchical arrays, beginning with the "object" type.
id	required	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.
parent	none	The id of a parent object in the same collection. This allows for the creation of hierarchical structures (such as folders).
modified	time submitted	The last-modified date, in Julian date format.
encryption	none	The URL of a Weave Encryption Record (WER) that defines how the payload is encrypted. No URL means that the payload is being sent unencrypted.
encoding	utf-8	The character set of the decrypted payload. payload (required) - The (possibly encrypted) JSON structure encapsualting the data of the record. This structure is defined separately for each WBO type.

Sample:

{
	"type": ["object", "cryptowrapper"],
	"id": "B1549145-55CB-4A6B-9526-70D370821BB5",
	"parent": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC",
	"modified": "2454725.98283",
	"encrytpion: "http://server/prefix/version/user/crypto-meta/B1549145-55CB-4A6B-9526-70D370821BB5",
	"encoding": "shift-JIS",
	"payload": "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.
timestamp	A Julian date.

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.
DELETE: Delete the object.

Other URLs will allow for structured access. All these support the 'start' and 'limit' parameters to allow for pagination:

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

GET: Returns a list of ids associated with the collection.
PUT: Takes an array of WBOs and adds/updates them within the collection. Identical to looping over a series of /id urls.
DELETE: Deletes all objects in this collection.

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

GET: Returns a list of ids that are children of the specified id.
PUT: No applicable function.
DELETE: Deletes the object in the collection with this ID and all of its children.

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

GET: Returns a list of ids modified within the collection since the timestamp given.
PUT: No applicable function.
DELETE: No applicable function. http://server/prefix/version/user/collection/since/timestamp

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.

• key_data (required) - the private key, passphrase encrypted.
• public_key (required) - the URI to the public key associated with this private key.

Sample Private Key payload:

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

Public Key

Public Key objects must be unencrypted.

• key_data (required) - the public key
• private_key (required) - the URI to the private key associated with this public key.

Sample Public Key payload:

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

Cryptometa

Cryptometa objects (type: "cryptometa") must be unencrypted.

• 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 (required) - 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 crypto-meta payload:

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