compared with
Version 3 by Sergey Avseyev
on Feb 26, 2013 10:35.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (2)

View Page History
You can find executable spec here: http://docs.couchbasenginx.apiary.io/

This document describes the REST API exposed to access Couchbase
resources

There are several terms we are using while describing this API.

|| Term || Definition||
| document | Arbitrary JSON or BLOB value. It could be referenced by its ID |
| bucket | The logical storage, which contains the documents. Like *database* in SQL world, or *collection* in mongodb |

Lets assume we have a bucket named {{wonderland}}.

h2. Document CRUD

Create document in the bucket
{code:none}
POST /wonderland
> Content-Type: application/json
{"name": "Alice", "type": "person"}
< 201
< X-Couchbase-CAS: 13023137187469131776
< Location: http://couchbasenginx.apiary.io/wonderland/0a4683e4b4b161f505d0c2ae0c3a1abf
{code}

You can also specify ID with POST request if you need to {{create}} the document with given ID.
{code:none}
POST /wonderland/alice
> Content-Type: application/json
{"name": "Alice", "type": "person"}
< 201
< X-Couchbase-CAS: 13023137187469131776
< Location: http://couchbasenginx.apiary.io/wonderland/alice
{code}

Note that when you are using POST request, the server is always supposed to create the new document. This means that you will get an error if the document already exists.
{code:none}
POST /wonderland/foobar
> Content-Type: application/json
{"foo": "bar"}
< 409
< Content-Type: application/json
< Content-Length: 74
{"error":"key_eexists","reason":"Key exists (with a different CAS value)"}
{code}

Update the document
{code:none}
PUT /wonderland/white-rabbit
> Content-Type: application/json
{"name": "Write Rabbit", "type": "rabbit"}
< 204
< X-Couchbase-CAS: 5045917818764787712
< Location: http://couchbasenginx.apiary.io/wonderland/white-rabbit
{code}

You can also specify {{X-Couchbase-CAS}} header and the server will perform optimistic lock before updating. This operation might fail on CAS mismatch
{code:none}
PUT /wonderland/duchess
> Content-Type: application/json
> X-Couchbase-CAS: 12870165639474053120
{"name": "Duchess", "type": "person"}
< 409
< Content-Type: application/json
< Content-Length: 74
{"error":"key_eexists","reason":"Key exists (with a different CAS value)"}
{code}

If the document being updated doesn't exist, you will get {{404 Not Found}} error
{code:none}
PUT /wonderland/red-king
{"name": "Red King", "type": "card"}
< 404
< Content-Type: application/json
< Content-Length: 45
{"error":"key_enoent","reason":"No such key"}
{code}

Removing document from the bucket
{code:none}
DELETE /wonderland/caterpillar
< 204
< X-Couchbase-CAS: 739012339596722176
{code}

You can also specify CAS value if you need to ensure you are removing know version of the document. In case of CAS mismatch you will get an error.
{code:none}
DELETE /wonderland/bill-the-lizard
> X-Couchbase-CAS: 2678097998852587520
< 409
< Content-Type: application/json
< Content-Length: 74
{"error":"key_eexists","reason":"Key exists (with a different CAS value)"}
{code}

If the document being removed doesn't exist, you will get {{404 Not Found}} error
{code:none}
DELETE /wonderland/jabberwock
< 404
< Content-Type: application/json
< Content-Length: 45
{"error":"key_enoent","reason":"No such key"}
{code}

Getting the document by ID. You can also control expiration time of the key using {{X-Couchbase-TTL}} header. The argument should be a ASCII representation of 32-bit number, which interpreted as absolute time in seconds if it is less than {{30 * 24 * 60 * 60}} or epoch time otherwise.
{code:none}
GET /wonderland/hatter
< 200
< Content-Type: application/json
< Content-Length: 36
< X-Couchbase-CAS: 14571488446784471040
{"name": "Hatter", "type": "person"}
{code}

In case when the given document ID isn't exist in the bucket you will get {{404 Not Found}}
{code:none}
GET /wonderland/red-queen
< 404
< Content-Type: application/json
< Content-Length: 45
{"error":"key_enoent","reason":"No such key"}
{code}