REST API reference

The Couchbase Server REST API enables you to manage a Couchbase Server deployment as well as perform operations such as storing design documents and querying for results.

Use the REST API to manage clusters, server nodes, and buckets, and to retrieve run-time statistics within a Couchbase Server deployment.

Description

When developing a Couchbase Server-compatible SDK, the REST API is used within your library to handle views. Views enable you to index and query data based on functions that you define.

The REST API should not be used to read or write data to the server. Data operations, such as set and get are handled by Couchbase Server SDKs. Using the REST API for CRUD does not scale as well as SDKs and does not offer the same level of data protection.

In addition, the Couchbase Web Console uses REST API endpoints for administrative tasks, such as creating a new bucket, adding a node to a cluster, or changing cluster settings.

Build your request starting from Couchbase Server cluster URIs. Be aware that URIs for resources may change from version to version. The URI hierarchies facilitate reuse of requests because they follow a similar pattern for accessing different parts of the system.

Basic principles

The Couchbase Server REST API is built on the following basic principles:

JSON Responses: The Couchbase Server REST API returns many responses as JavaScript Object Notation (JSON). On that note, you may find it convenient to read responses with a tool that specifically parses and formats JSON output. Some responses may have an empty body, but indicate the response with standard HTTP codes. For more information, see RFC 4627 at www.json.org.
HTTP Basic Access Authentication: The Couchbase Server REST API, web console user interface, and command line utilities all use HTTP basic authentication.
Versatile Server Nodes: All server nodes in a cluster share the same properties and can handle any requests made via the REST API. You can make a REST API request against any node in a cluster

If the server node cannot directly service a request, it will forward the request to the appropriate server node, retrieve the response, and send the response to the client.

Types of resources

There are a number of different resources within the Couchbase Server and these resources require a different URI/RESTful-endpoint in order to perform operations:

Server nodes: A Couchbase Server instance, also known as a server or server node, is a physical or virtual machine running Couchbase Server. Each server node is a member of a cluster.
Cluster/Pool: A cluster is a group of one or more servers and is a collection of physical resources that are grouped together and provide services and a management interface. A single default cluster exists for every deployment of Couchbase Server. A server node, or instance of Couchbase Server, is a member of a cluster. Couchbase Server collects run-time statistics for clusters, maintaining an overall pool-level data view of counters and periodic metrics of the overall system. The Couchbase Server REST API can be used to retrieve historic statistics for a cluster.
Buckets: A bucket is a logical grouping of data within a cluster. It provides a name space for all the related data in an application. You can use the same key in two different buckets and they are treated as unique items by Couchbase Server.

Couchbase Server collects run-time statistics for buckets, maintaining an overall bucket-level data view of counters and periodic metrics of the system. Buckets are categorized by storage type. Memcached buckets are for in-memory, RAM-based information. Couchbase buckets are for persisted data.
Views: Views enable you to index and query data based on logic you specify. You can also use views to perform calculations and aggregations, such as statistics, for items in Couchbase Server.
Cross Datacenter Replication (XDCR): Cross Datacenter Replication (XDCR) enables automatic replication of data between clusters and between data buckets. The major benefits include the ability to restore data from one Couchbase Server cluster to another cluster after system failure and the ability to provide copies of data on clusters that are physically closer to end users.

HTTP request headers

The following HTTP request headers are used to create requests:

Header Supported Values Description of Use Required

Header	Supported Values	Description of Use	Required
Accept	Comma-delimited list of media types or media type patterns.	Indicates to the server what media type(s) this client is prepared to accept.	Recommended
Authorization	`Basic` plus username and password (per RFC 2617).	Identifies the authorized user making this request.	No, unless secured
Content-Length	Body Length (in bytes)	Describes the size of the message body.	Yes, on requests that contain a message body.
Content-Type	Content type	Describes the representation and syntax of the request message body.	Yes, on requests that contain a message body.
Host	Origin host name	Required to allow support of multiple origin hosts at a single IP address.	All requests
X-YYYYY-Client-Specification-Version	String	Declares the specification version of the YYYYY API that this client was programmed against.	No

Comma-delimited list of media types or media type patterns.

Indicates to the server what media type(s) this client is prepared to accept.

Recommended

Authorization

Basic plus username and password (per RFC 2617).

Identifies the authorized user making this request.

No, unless secured

Content-Length

Body Length (in bytes)

Describes the size of the message body.

Yes, on requests that contain a message body.

Content-Type

Content type

Describes the representation and syntax of the request message body.

Yes, on requests that contain a message body.

Host

Origin host name

Required to allow support of multiple origin hosts at a single IP address.

All requests

X-YYYYY-Client-Specification-Version

String

Declares the specification version of the YYYYY API that this client was programmed against.

HTTP response codes

The Couchbase Server returns one of the following HTTP status codes in response to REST API requests:

HTTP response	Description
200 OK	Successful request and an HTTP response body returns. If this creates a new resource with a URI, the 200 status will also have a location header containing the canonical URI for the newly created resource.
201 Created	Request to create a new resource is successful, but no HTTP response body returns. The URI for the newly created resource returns with the status code.
202 Accepted	The request is accepted for processing, but processing is not complete. Per HTTP/1.1, the response, if any, SHOULD include an indication of the request’s current status, and either a pointer to a status monitor or some estimate of when the request will be fulfilled.
204 No Content	The server fulfilled the request, but does not need to return a response body.
400 Bad Request	The request could not be processed because it contains missing or invalid information, such as validation error on an input field, a missing required value, and so on.
401 Unauthorized	The credentials provided with this request are missing or invalid.
403 Forbidden	The server recognized the given credentials, but you do not possess proper access to perform this request.
404 Not Found	URI provided in a request does not exist.
405 Method Not Allowed	The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this URI.
406 Not Acceptable	The resource identified by this request cannot create a response corresponding to one of the media types in the Accept header of the request.
409 Conflict	A create or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server. For example, an attempt to create a new resource with a unique identifier already assigned to some existing resource.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented	The server does not currently support the functionality required to fulfill the request.
503 Service Unavailable	The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

HTTP response

Description

200 OK

Successful request and an HTTP response body returns. If this creates a new resource with a URI, the 200 status will also have a location header containing the canonical URI for the newly created resource.

201 Created

Request to create a new resource is successful, but no HTTP response body returns. The URI for the newly created resource returns with the status code.

202 Accepted

The request is accepted for processing, but processing is not complete. Per HTTP/1.1, the response, if any, SHOULD include an indication of the request’s current status, and either a pointer to a status monitor or some estimate of when the request will be fulfilled.

204 No Content

The server fulfilled the request, but does not need to return a response body.

400 Bad Request

The request could not be processed because it contains missing or invalid information, such as validation error on an input field, a missing required value, and so on.

401 Unauthorized

The credentials provided with this request are missing or invalid.

403 Forbidden

The server recognized the given credentials, but you do not possess proper access to perform this request.

404 Not Found

URI provided in a request does not exist.

405 Method Not Allowed

The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this URI.

406 Not Acceptable

The resource identified by this request cannot create a response corresponding to one of the media types in the Accept header of the request.

409 Conflict

A create or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server. For example, an attempt to create a new resource with a unique identifier already assigned to some existing resource.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

501 Not Implemented

The server does not currently support the functionality required to fulfill the request.

503 Service Unavailable

The server is currently unable to handle the request due to temporary overloading or maintenance of the server.