This document describes the REST API exposed to access Couchbase
What it doesn't describe:
- auth scheme, on this step you might only protect your API endpoint
using nginx built-in means
There are several terms we are using while describing this API.
|mount point||The part of URI which where couchbase nginx module connected|
|document||Arbitrary JSON or BLOB value. It could be referenced by its ID|
The Couchbase API could be mount to any endpoint in your application,
and during configuration the bucket name and credentials should be
specified like this:
The config section above tell nginx to use /wonderland/ mount
point to expose Couchbase API.
By default only Document API will be mounted, i.e. only CRUD
operations can be executed there. Because in Couchbase itself both
Document and Views APIs lives in completely different namespaces, the
nginx module also keeps them separate. The example below will mount
views and the documents into the common root.
The connection configuration could be shared amound the locations
The module maps basic data operations to HTTP methods. The table below
assumes that the bucket mount to /storage location:
|Couchbase operation||HTTP method||Comments|
|get "foo"||GET /storage/foo|
|add "foo" "bar"||POST /storage/foo||document goes in request's body, fails if ID exists already|
|POST /storage||the same as above, but will generate ID|
|set "foo" "bar"||PUT /storage/foo||document goes in request's body|
|delete "foo"||DELETE /storage/foo|
Apart from HTTP methods, it is possible to use arguments in query
string, to specify the command. To do so, the name of the parameter
must be specified in the config:
The snippet above will translate this URI /storage/foo?cmd=replace&exptime=40
to the replace "foo" ... command with expiration of 40 seconds. In
the same way can be controller ID, value, flags and expiration time.
The rest of the section demonstrates various example of usage the API,
including optimistic locking with CAS. It assumes the following config:
Create document in the bucket
You can also specify ID with POST request if you need to create the
document with given ID.
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.
Update the document
You can also specify If-Match header and the server will perform
optimistic lock before updating. This operation might fail *412
If the document being updated doesn't exist, you will get *404 Not
Removing document from the bucket
You can also specify If-Match header if you need to ensure you are
removing know version of the document.
If the document being removed doesn't exist, you will get *404 Not
Getting the document by ID.
In case when the given document ID isn't exist in the bucket you will
get 404 Not Found
Use HEAD request to skip the document body
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):
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.
The 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.
As mentioned above, the view endpoint should be mount separately
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):
The result will look like
You can pass the any of supported query parameters, like
include_docs=true for example (note that rev field replaced with
You can find executable spec here: http://docs.ngxcbm.apiary.io/