This spec describes a standard JSON-based REST API with an optional batch mode.  Batch mode allows you to manipulate multiple resources on a single service with a single request.  This can improve performance; particularly when creating or deleting a large number of resources.  It is NOT a replacement for transactions.

JSON Format

All JSON documents exchanged with the server are structured to allow meta-data to be included in addition to the content.  These documents are conceptually similar to the Atom PubSub API but simplified to use JSON.

All documents have the following structure:

{

  "id": ID, // optional id for resource. resource with same ID are joined

  "version": "1234", // optional version number for content

  "content": { ... } | [ ... ] // content item,

  "links": [

    "self": "/http/FOO", // URI to self

    "batch": "/FOO", // URI for batch mode

    "put": "/FOO?rev=1234", // optional URI for updating content

    "post": "/FOO?rev=1234", // optional URI for creating new content

    "delete": "/FOO?rev=1234", // optional URI for deleting content

  ]

}

Batch Mode

Batch mode is implemented as a single endpoint.  To send batch, POST to URL:

[

  { method:     "GET",

    uri:        "/foo",

    X-If-Error: "continue",

    X-If-Fail:  "cancel",

    If-Modified-Since: "...",

  }, {

    method:     "PUT",

    uri:        "/foo/123?alt=json&version=1234",

    E-Tag:      "1234",

    body:       { ... }

  }

]