Version 5 by Sergey Avseyev
on Feb 26, 2013 11:39.
<< Changes from 4 to 5
compared with
Version 6 by Sergey Avseyev
on Feb 26, 2013 17:14.
Changes from 6 to 7 >>
Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (68)

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

What it doesn't describe:

* auth scheme, on this step you might only protect your API endpoint using nginx built-in means
* expiration handling. in Couchbase database it is possible to associate with the key expiration time. This feature will be exposed later

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

...
h2. Document CRUD

This section shows how to perform simple Create, Retrieve, Update and Delete operations

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

You can also specify ID with POST request if you need to {{create}} *create* the document with given ID.
{code:none}
POST /wonderland/alice
> Content-Type: application/json
{"name": "Alice", "species": "human"} {"name":"Alice","species":"human"}
< 201
< X-Couchbase-CAS: 13023137187469131776
< ETag: "f5b8da2cf1570000"
< Location: http://couchbasenginx.apiary.io/wonderland/alice
{code}
...
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 ETag value)"}
{code}

...
PUT /wonderland/white-rabbit
> Content-Type: application/json
{"name": "Write Rabbit", "species": "rabbit"} {"name":"Write Rabbit","species":"rabbit"}
< 204
< X-Couchbase-CAS: 5045917818764787712
< ETag: "3d24e52cf1570000"
< Location: http://couchbasenginx.apiary.io/wonderland/white-rabbit
{code}

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

If the document being updated doesn't exist, you will get {{404 *404 Not Found}} Found* error
{code:none}
PUT /wonderland/sheep
{"name": "Sheep", "species": "sheep"} {"name":"Sheep","species":"sheep"}
< 404
< Content-Type: application/json
...
DELETE /wonderland/caterpillar
< 204
< X-Couchbase-CAS: 739012339596722176
< ETag: "7f463c2df1570000"
{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.

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


If the document being removed doesn't exist, you will get {{404 *404 Not Found}} Found* error
{code:none}
DELETE /wonderland/jabberwock
...
{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.
Getting the document by ID.
{code:none}
GET /wonderland/hatter
...
< Content-Type: application/json
< Content-Length: 36
< X-Couchbase-CAS: 14571488446784471040
< ETag: "5d45c301fc570000"
{"name": "Hatter", "species": "human"} {"name":"Hatter","species":"human"}
{code}

In case when the given document ID isn't exist in the bucket you will get {{404 *404 Not Found}} Found*
{code:none}
GET /wonderland/red-queen
...
{code}

Use *HEAD* request to skip the document body HEAD /wonderland/gryphon
{code:none}
< 200
< Content-Type: application/json
< ETag: "55c3a92df1570000"
{code}

Each operation is carry ETag, which internally is CAS value. The ETag value can be used in the conditional requests with *If-Match*, *If-None-Match*. See examples of *If-Match* above.

Check if the key has been modified (in this case the server responds that it wasn't modified):
{code:none}
HEAD /wonderland/dormouse
> If-None-Match: "3f5b792df1570000"
< 304
{code}


h2. Couchbase Views

This section shows more advanced server feature: View indexes

One of the features of the Couchbase is ability to build efficient indexes leveraging Map/Reduce. They are called Views and you can define them on Admin Console UI.

This module allows you to query your views proxying them to Couchbase. All arguments will be transparently passed to Couchbase and the result will be streamed back.

For example we have a view {{all}} *all* defined in the design document {{characters}}. *characters*. It is simple map which will just emit all known characters (without any reduce function):

{code:javascript}
...
{code}

The result will look like (note: when *id* isn't accessible like for reduced views, the *meta* will be missing too)
{code:none}
GET /wonderland/_design/characters/_view/all
...
< Transfer-Encoding: chunked
< Content-Type: application/json
{"total_rows":120,"rows":[
{"id":"bill-the-lizard","key":"bill-the-lizard","value":null}, {"id":"alice","key":"alice","value":null,"meta":{"etag":"f5b8da2cf1570000"}},
{"id":"cheshire-cat","key":"cheshire-cat","value":null}, {"id":"bill-the-lizard","key":"bill-the-lizard","value":null,"meta":{"etag":"accb302df1570000"}},
{"id":"dodo","key":"dodo","value":null}, {"id":"caterpillar","key":"caterpillar","value":null,"meta":{"etag":"7f463c2df1570000"}},
{"id":"duchess","key":"duchess","value":null}, {"id":"cheshire-cat","key":"cheshire-cat","value":null,"meta":{"etag":"5b99582df1570000"}},
{"id":"eaglet","key":"eaglet","value":null}, {"id":"dodo","key":"dodo","value":null,"meta":{"etag":"2fe2ed2cf1570000"}},
{"id":"gryphon","key":"gryphon","value":null}, {"id":"dormouse","key":"dormouse","value":null,"meta":{"etag":"3f5b792df1570000"}},
{"id":"king-of-hearts","key":"king-of-hearts","value":null}, {"id":"duchess","key":"duchess","value":null,"meta":{"etag":"a8bc492df1570000"}},
{"id":"march-hare","key":"march-hare","value":null}, {"id":"duck","key":"duck","value":null,"meta":{"etag":"e076132df1570000"}},
{"id":"mock-turtle","key":"mock-turtle","value":null}, {"id":"eaglet","key":"eaglet","value":null,"meta":{"etag":"b9bd062df1570000"}},
{"id":"queen-of-hearts","key":"queen-of-hearts","value":null} {"id":"gryphon","key":"gryphon","value":null,"meta":{"etag":"55c3a92df1570000"}},
{"id":"hatter","key":"hatter","value":null,"meta":{"etag":"5d45c301fc570000"}},
{"id":"king-of-hearts","key":"king-of-hearts","value":null,"meta":{"etag":"4e1c9f2df1570000"}},
{"id":"knave-of-hearts","key":"knave-of-hearts","value":null,"meta":{"etag":"43fa922df1570000"}},
{"id":"lory","key":"lory","value":null,"meta":{"etag":"01f6fa2cf1570000"}},
{"id":"march-hare","key":"march-hare","value":null,"meta":{"etag":"08f6642df1570000"}},
{"id":"mock-turtle","key":"mock-turtle","value":null,"meta":{"etag":"11a8b52df1570000"}},
{"id":"mouse","key":"mouse","value":null,"meta":{"etag":"fa38ea2cf1570000"}},
{"id":"pat","key":"pat","value":null,"meta":{"etag":"8bd71f2df1570000"}},
{"id":"queen-of-hearts","key":"queen-of-hearts","value":null,"meta":{"etag":"f72c862df1570000"}},
{"id":"white-rabbit","key":"white-rabbit","value":null,"meta":{"etag":"3d24e52cf1570000"}},
]
}
{code}


You can pass the any of supported query parameters, like {{include_docs=true}} *include_docs=true* for example:
{code:none}
GET /wonderland/_design/characters/_view/all?include_docs=true
...
< Transfer-Encoding: chunked
< Content-Type: application/json
{"total_rows":120,"rows":[
{"id":"bill-the-lizard","key":"bill-the-lizard","value":null,"doc":{"meta":{"id":"bill-the-lizard","rev":"1-000050d16a33cfcb0000000000000000","expiration":0,"flags":0},"json":{"name":"Bill the Lizard","species":"lizard"}}},
{"id":"cheshire-cat","key":"cheshire-cat","value":null,"doc":{"meta":{"id":"cheshire-cat","rev":"1-000050d16a3c44970000000000000000","expiration":0,"flags":0},"json":{"name":"Cheshire Cat","species":"cat"}}},
{"id":"dodo","key":"dodo","value":null,"doc":{"meta":{"id":"dodo","rev":"1-000050d16a2676470000000000000000","expiration":0,"flags":0},"json":{"name":"Dodo","species":"bird"}}}, {"id":"alice","key":"alice","value":null,"meta":{"etag":"f5b8da2cf1570000"},"json":{"name":"Alice","species":"human"}},
{"id":"bill-the-lizard","key":"bill-the-lizard","value":null,"meta":{"etag":"accb302df1570000"},"json":{"name":"Bill the Lizard","species":"lizard"}},
{"id":"duchess","key":"duchess","value":null,"doc":{"meta":{"id":"duchess","rev":"1-000050d16a394b5b0000000000000000","expiration":0,"flags":0},"json":{"name":"Duchess","species":"human"}}}, {"id":"caterpillar","key":"caterpillar","value":null,"meta":{"etag":"7f463c2df1570000"},"json":{"name":"Caterpillar","species":"caterpillar"}},
{"id":"cheshire-cat","key":"cheshire-cat","value":null,"meta":{"etag":"5b99582df1570000"},"json":{"name":"Cheshire Cat","species":"cat"}},
{"id":"eaglet","key":"eaglet","value":null,"doc":{"meta":{"id":"eaglet","rev":"1-000050d16a2bac3f0000000000000000","expiration":0,"flags":0},"json":{"name":"Eaglet","species":"bird"}}}, {"id":"dodo","key":"dodo","value":null,"meta":{"etag":"2fe2ed2cf1570000"},"json":{"name":"Dodo","species":"bird"}},
{"id":"gryphon","key":"gryphon","value":null,"doc":{"meta":{"id":"gryphon","rev":"1-000050d16a50bf4a0000000000000000","expiration":0,"flags":0},"json":{"name":"Gryphon","species":"gryphon"}}}, {"id":"dormouse","key":"dormouse","value":null,"meta":{"etag":"3f5b792df1570000"},"json":{"name":"Dormouse","species":"dormouse"}},
{"id":"king-of-hearts","key":"king-of-hearts","value":null,"doc":{"meta":{"id":"king-of-hearts","rev":"1-000050d16a4de61e0000000000000000","expiration":0,"flags":0},"json":{"name":"King of Hearts","species":"card"}}},
{"id":"march-hare","key":"march-hare","value":null,"doc":{"meta":{"id":"march-hare","rev":"1-000050d16a3f1afa0000000000000000","expiration":0,"flags":0},"json":{"name":"March Hare","species":"hare"}}},
{"id":"mock-turtle","key":"mock-turtle","value":null,"doc":{"meta":{"id":"mock-turtle","rev":"1-000050d16a53d7770000000000000000","expiration":0,"flags":0},"json":{"name":"Mock Turtle","species":"turtle"}}},
{"id":"queen-of-hearts","key":"queen-of-hearts","value":null,"doc":{"meta":{"id":"queen-of-hearts","rev":"1-000050d16a4765350000000000000000","expiration":0,"flags":0},"json":{"name":"Queen of Hearts","species":"card"}}}
{"id":"duchess","key":"duchess","value":null,"meta":{"etag":"a8bc492df1570000"},"json":{"name":"Duchess","species":"human"}},
{"id":"duck","key":"duck","value":null,"meta":{"etag":"e076132df1570000"},"json":{"name":"Duck","species":"bird"}},
{"id":"eaglet","key":"eaglet","value":null,"meta":{"etag":"b9bd062df1570000"},"json":{"name":"Eaglet","species":"bird"}},
{"id":"gryphon","key":"gryphon","value":null,"meta":{"etag":"55c3a92df1570000"},"json":{"name":"Gryphon","species":"gryphon"}},
{"id":"hatter","key":"hatter","value":null,"meta":{"etag":"5d45c301fc570000"},"json":"foo"},
{"id":"king-of-hearts","key":"king-of-hearts","value":null,"meta":{"etag":"4e1c9f2df1570000"},"json":{"name":"King of Hearts","species":"card"}},
{"id":"knave-of-hearts","key":"knave-of-hearts","value":null,"meta":{"etag":"43fa922df1570000"},"json":{"name":"Knave of Hearts","species":"card"}},
{"id":"lory","key":"lory","value":null,"meta":{"etag":"01f6fa2cf1570000"},"json":{"name":"Lory","species":"bird"}},
{"id":"march-hare","key":"march-hare","value":null,"meta":{"etag":"08f6642df1570000"},"json":{"name":"March Hare","species":"hare"}},
{"id":"mock-turtle","key":"mock-turtle","value":null,"meta":{"etag":"11a8b52df1570000"},"json":{"name":"Mock Turtle","species":"turtle"}},
{"id":"mouse","key":"mouse","value":null,"meta":{"etag":"fa38ea2cf1570000"},"json":{"name":"Mouse","species":"mouse"}},
{"id":"pat","key":"pat","value":null,"meta":{"etag":"8bd71f2df1570000"},"json":{"name":"Pat","species":"pig"}},
{"id":"queen-of-hearts","key":"queen-of-hearts","value":null,"meta":{"etag":"f72c862df1570000"},"json":{"name":"Queen of Hearts","species":"card"}},
{"id":"white-rabbit","key":"white-rabbit","value":null,"meta":{"etag":"3d24e52cf1570000"},"json":{"name":"White Rabbit","species":"rabbit"}}
]
}
{code}

h2. Misc

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