CloudStore API

CloudStore is a key/value data store accessed via a RESTful JSON API over HTTP. Data is stored in a tree structure. All keys are accessible by an unique URL. All values are JSON.

API Methods

method	example	description
GET	GET /users/joe/address	Get data stored at key
GET	GET /users/joe/* GET** /users/joe/[a]-[b]	Get all keys (*) or get a range of keys
PUT	PUT /users/joe/email POST /users/joe/email?method=PUT	Create or update data. Merges attributes if data is JSON object.
REPLACE**	POST /users/joe/address?method=REPLACE	Same as doing a DELETE and PUT. Does not merge attributes with existing object.
DELETE	DELETE /users/joe/address GET /users/joe/address?method=DELETE DELETE /users/joe/*	Delete key and data or delete all keys (*)

** Not yet implemented

Keys

Keys can be any valid URI. Reserved characters must be escaped with a backslash "".

Reserved characters: *[ ] * *

VALID KEYS

/users/joe
/users/joe/address
/u^a9$!/(abc)4
/users/u\[0\]/address

INVALID KEYS

/u&a/joe         '&' is invalid
/u?a/joe         '?' is invalid
/users/joe[0]    '[' and ']' are invalid

Writing

Data is written to the CloudStore by sending in JSON via HTTP PUT or optionally via HTTP POST and a method query parameter.

PUT /users/joe/email
"joe@example.com"

PUT /users/joe/admin
true

PUT /users/joe/address
{
  "street": "185 Clara St.",
  "city": "San Francisco",
  "state_code": "CA",
  "country_code": "USA"
}

When a JSON object is stored, the default behavior of PUT is to merge attributes...

PUT /users/joe/address
{
  "street": "123 Some St."
}

...will result in the following assuming the previous address value already included city, state_code, and country_code.

{
  "street": "123 Some St.",
  "city": "San Francisco",
  "state_code": "CA",
  "country_code": "USA"
}

To replace the original object instead of merging, pass in the method=REPLACE query parameter...

PUT /users/joe/address?method=REPLACE
{
  "street": "123 Some St."
}

...will result in...

{
  "street": "123 Some St."
}

Reading

Reads can fetch either the value for the key or fetch the subkeys.

Fetch value...

GET /users/joe/address
{
  "street": "185 Clara St.",
  "city": "San Francisco",
  "state_code": "CA",
  "country_code": "USA"
}

Subkeys are fetched using key query syntax with * and [].

Fetch all subkeys...

GET /users/joe/*
{
  "address": {"street": "185 Clara St.", "city": ...},
  "email": "joe@example.com"
}

Fetch keys matching a prefix...

GET /users/joe/[add*]
{
  "address": {"street": "185 Clara St.", "city": ...}
}

Fetch a range of keys...

GET /users/joe/[a*]-[e*]
{
  "address": {"street": "185 Clara St.", "city": ...},
  "email": "joe@example.com"
}

Fetch multiple keys...

GET /users/joe/[address],[email]
{
  "address": {"street": "185 Clara St.", "city": ...},
  "email": "joe@example.com"
}

Authentication

Authentication is managed with OAuth tokens unless otherwise configured.

Pub/Sub

Clients can subscribe to changes in data via web hook callbacks.