You are viewing an old version of this page. View the current version.
Compare with Current |
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.
Document CRUD
Create document in the bucket
POST /wonderland
> Content-Type: application/json
{"name": "Alice", "species": "human"}
< 201
< X-Couchbase-CAS: 13023137187469131776
< Location: http://couchbasenginx.apiary.io/wonderland/0a4683e4b4b161f505d0c2ae0c3a1abf
You can also specify ID with POST request if you need to create the document with given ID.
POST /wonderland/alice
> Content-Type: application/json
{"name": "Alice", "species": "human"}
< 201
< X-Couchbase-CAS: 13023137187469131776
< Location: http://couchbasenginx.apiary.io/wonderland/alice
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.
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)"}
Update the document
PUT /wonderland/white-rabbit
> Content-Type: application/json
{"name": "Write Rabbit", "species": "rabbit"}
< 204
< X-Couchbase-CAS: 5045917818764787712
< Location: http://couchbasenginx.apiary.io/wonderland/white-rabbit
You can also specify X-Couchbase-CAS header and the server will perform optimistic lock before updating. This operation might fail on CAS mismatch
PUT /wonderland/duchess
> Content-Type: application/json
> X-Couchbase-CAS: 12870165639474053120
{"name": "Duchess", "species": "human"}
< 409
< Content-Type: application/json
< Content-Length: 74
{"error":"key_eexists","reason":"Key exists (with a different CAS value)"}
If the document being updated doesn't exist, you will get 404 Not Found error
PUT /wonderland/sheep
{"name": "Sheep", "species": "sheep"}
< 404
< Content-Type: application/json
< Content-Length: 45
{"error":"key_enoent","reason":"No such key"}
Removing document from the bucket
DELETE /wonderland/caterpillar < 204 < X-Couchbase-CAS: 739012339596722176
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.
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)"}
If the document being removed doesn't exist, you will get 404 Not Found error
DELETE /wonderland/jabberwock
< 404
< Content-Type: application/json
< Content-Length: 45
{"error":"key_enoent","reason":"No such key"}
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.
GET /wonderland/hatter
< 200
< Content-Type: application/json
< Content-Length: 36
< X-Couchbase-CAS: 14571488446784471040
{"name": "Hatter", "species": "human"}
In case when the given document ID isn't exist in the bucket you will get 404 Not Found
GET /wonderland/red-queen
< 404
< Content-Type: application/json
< Content-Length: 45
{"error":"key_enoent","reason":"No such key"}
Couchbase Views
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 defined in the design document characters. It is simple map which will just emit all known characters (without any reduce function):
function (doc, meta) { emit(meta.id, null); }
The result will look like
GET /wonderland/_design/characters/_view/all
< 200
< Transfer-Encoding: chunked
< Content-Type: application/json
{"total_rows":10,"rows":[
{"id":"bill-the-lizard","key":"bill-the-lizard","value":null},
{"id":"cheshire-cat","key":"cheshire-cat","value":null},
{"id":"dodo","key":"dodo","value":null},
{"id":"duchess","key":"duchess","value":null},
{"id":"eaglet","key":"eaglet","value":null},
{"id":"gryphon","key":"gryphon","value":null},
{"id":"king-of-hearts","key":"king-of-hearts","value":null},
{"id":"march-hare","key":"march-hare","value":null},
{"id":"mock-turtle","key":"mock-turtle","value":null},
{"id":"queen-of-hearts","key":"queen-of-hearts","value":null}
]
}
You can pass the any of supported query parameters, like include_docs=true for example:
GET /wonderland/_design/characters/_view/all?include_docs=true
< 200
< Transfer-Encoding: chunked
< Content-Type: application/json
{"total_rows":10,"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":"duchess","key":"duchess","value":null,"doc":{"meta":{"id":"duchess","rev":"1-000050d16a394b5b0000000000000000","expiration":0,"flags":0},"json":{"name":"Duchess","species":"human"}}},
{"id":"eaglet","key":"eaglet","value":null,"doc":{"meta":{"id":"eaglet","rev":"1-000050d16a2bac3f0000000000000000","expiration":0,"flags":0},"json":{"name":"Eaglet","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":"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"}}}
]
}