REST API reference

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.

Tip: 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.

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
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

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.