REST API

This document describes the API as of ShareJS v0.7. ShareJS 0.6 had a REST interface, but it worked differently.

ShareJS can expose documents using simple REST queries. shareClient.rest() returns middleware which can be installed and used in your connect or express app.

For example:

var connect = require('connect');

// Create a sharejs instance as normal
share = sharejs.server.createClient {backend}

var app = connect();
app.use('/shareDocs', share.rest());

Then GET /shareDocs/users/fred will fetch the fred document in the users collection.

Exposed methods

The REST middleware exposes the following API endpoints:

Fetch document - GET & HEAD /:collection/:doc

Get the named document. The body of the result contains the document itself.

• If the document snapshot is a string (text document or JSON document with a string as the body), the document will be returned as the body of the result and Content-Type: text/plain
• If the document is not a string, the body is JSON-encoded and returned with Content-Type: application/json

The response also sets X-OT-Version and X-OT-Type.

The server will return 404 if the document doesn't exist (it doesn't have a type set). In this case, X-OT-Version is still set but X-OT-Type is not.

If you just want to know the version and type, you can send a HEAD request instead of GET.

Eg:

Here I GET a text document. Note the content type is text/plain and the OT type is specified in the response:

$ curl -i 'http://localhost:7007/doc/users/seph'
HTTP/1.1 200 OK
X-OT-Version: 37
X-OT-Type: http://sharejs.org/types/textv1
Content-Type: text/plain
Date: Wed, 21 Aug 2013 00:31:56 GMT
Connection: keep-alive
Transfer-Encoding: chunked

sfdawef
awfe
e

Or a JSON document:

$ curl -i 'http://localhost:7007/doc/users/blah'
HTTP/1.1 200 OK
X-OT-Version: 4
X-OT-Type: http://sharejs.org/types/JSONv0
Content-Type: application/json
Date: Wed, 21 Aug 2013 00:32:54 GMT
Connection: keep-alive
Transfer-Encoding: chunked

{"x":5}

Get ops - GET /:collection/:doc/ops?from:FROM&to:TO

Get the operations for the specified document. This returns all operations from versions [FROM,TO). They should both be non-negative numbers. FROM defaults to 0 if not specified. If TO is not specified, all operations from FROM are returned.

The operations are returned as a JSON list.

Eg:

Get all ops in a document:

$ curl 'http://localhost:7007/doc/users/seph/ops'
[{"src":"1eb7e54df470511c5252f3c26b90b718","seq":1,"create":{"type":"http://sharejs.org/types/textv1","data":null},"v":0},
{"src":"1eb7e54df470511c5252f3c26b90b718","seq":2,"op":["a"],"v":1},
{"src":"1eb7e54df470511c5252f3c26b90b718","seq":3,"op":[1,"s"],"v":2},
{"src":"1eb7e54df470511c5252f3c26b90b718","seq":4,"op":[2,"d"],"v":3},
{"src":"1eb7e54df470511c5252f3c26b90b718","seq":5,"op":[3,"f"],"v":4}]

Or you can get just a few operations:

$ curl 'http://localhost:7007/doc/users/seph/ops?from=1&to=3'
[{"src":"1eb7e54df470511c5252f3c26b90b718","seq":2,"op":["a"],"v":1},
{"src":"1eb7e54df470511c5252f3c26b90b718","seq":3,"op":[1,"s"],"v":2}]

The version numbers are provided for convenience - they can always be inferred from your request. You should probably ignore the src and seq numbers - together they uniquely globally identify an operation.

Submit Operations - POST /:collection/:doc {v:10, op:['hi']}

You can submit an operation to a document by POST-ing the operation to the document endpoint. The object you post is an opData object. Op data is a JSON object with the following fields:

• v: Version of the document to submit against. This should be as recent as possible. The version field is optional to make creating documents easier, but you should almost always include it. If not specified, the version defaults to the current version of the document when the operation reaches the backend.
• create: A create operation. This is used to set the type of a document (which creates it). If specified, the value should contain {type:<TYPE URI>, data:<INITIAL DATA>}. Initial data is optional.
• op: The operation itself. This operation format must match the document's type, and the document must exist. For example, an operation to delete characters 10-30 in a text document would be [10, {d:20}]. See the documentation on the type you're using for specifics. JSON operations are described here.
• del: Delete the document, which unsets the document's type. The value should be true.

Your operation should only contain one of the create/op/del fields. If you don't specify any, your operation will be a no-op, bumping the version but having no effect on the document.

The server will respond with a JSON object containing:

• v: The applied version, which is the version at which your operation was applied. This is usually the version specified by your operation.
• ops: This is a list containing any operation by which your operation was transformed.

Eg:

Create a JSON document on the server:

$ curl -X POST -d '{"v":0,"create":{"type":"http://sharejs.org/types/JSONv0","data":{"super":"good"}}}' 'http://localhost:7007/doc/users/nate'
{"v":0,"ops":[]}

$ curl 'http://localhost:7007/doc/users/nate'
{"super":"good"}

Edit it:

$ curl -X POST -d '{"v":1,"op":[{"p":["super"],"od":"good","oi":"bad"}]}' 'http://localhost:7007/doc/users/nate'
{"v":1,"ops":[]}

$ curl 'http://localhost:7007/doc/users/nate'
{"super":"bad"}

If another user tried to edit the document at the same time:

$ curl -X POST -d '{"v":1,"op":[{"p":["super"],"od":"good","oi":"great"}]}' 'http://localhost:7007/doc/users/nate'
{"v":2,"ops":[{"op":[{"p":["super"],"od":"good","oi":"bad"}],"v":1}]}

$ curl 'http://localhost:7007/doc/users/nate'
{"super":"great"}

Create a document - PUT /:collection/:doc {type:TYPE, data:INITIAL DATA}

You can simply PUT a document to create it if it doesn't already exist. PUT {...} is a shorthand for POST {create:{...}}. The version is not specified in the operation.

The response will either be 200 OK or 409 Conflict.

Delete a document - DELETE /:collection/:doc

You can delete a document by simply issuing a RESTful DELETE command. Deleting a document does not delete any of the document's operations - it simply sets the type to null in the backend and removes the document's snapshot. The document can be recreated after its been deleted just like any document that doesn't really exist.

Just like other operations, a delete operation increments the version number.