REST API reference
The REST API supports the management of Couchbase-Server clusters.
The REST API supports the management of Couchbase-Server clusters. This includes cluster-creation and the definition of nodes, services, and server groups. The API also supports the extensive retrieval of statistics.
This page provides a complete list of HTTP methods and URIs. It also lists HTTP Request Headers and HTTP Response Codes.
Nodes and Clusters API
The Cluster API provides support for managing and retrieving information on clusters. It also provides support for managing rebalance, failover, and server group awareness. The APIs for each area are assigned a table, below.
Cluster Initialization and Provisioning
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Node Addition and Removal
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
Rebalance
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Manual-Failover
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
Auto-Failover
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
POST |
|
|
|
|
Settings and Connections
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Status and Events
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Statistics
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
Buckets API
Couchbase Server keeps items in buckets. Before an item can be saved, a bucket must exist for it. Buckets can be created and managed by means of the following REST API.
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Scopes and Collections API
Couchbase Server provides scopes and collections; allowing documents to be categorized and organized, within a bucket. The REST API provided for the creation and management of scopes and collections is listed below.
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Memory and Storage API
Memory quotas can be allocated to services, and the current allocations retrieved. During cluster initialization, the on-disk paths for services can be specified on a per node basis.
Reader and writer threads can be configured, to ensure that disk access is highly performant.
Compaction can be managed: this is used by Couchbase Server to relocate on-disk data; so as to ensure the data’s closest-possible proximity, and thereby reclaim fragments of unused disk-space. The periodic compaction of a bucket’s data helps to ensure the ongoing efficiency of both reads and writes.
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Server Groups API
Server Group Awareness provides enhanced availability. Specifically, it protects a cluster from large-scale infrastructure failure, through the definition of groups. Its REST API is expressed by the following table.
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
XDCR API
Cross Data Center Replication (XDCR) replicates data between a source bucket and a target bucket. The buckets may be located on different clusters, and in different data centers: this provides protection against data-center failure, and also provides high-performance data-access for globally distributed, mission-critical applications. XDCR is supported by the REST API shown in the table below.
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Security API
The Security REST API provides the endpoints for general security, for authentication, and for authorization. These APIs are listed in the tables below.
General Security
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Authentication
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Authorization
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Query Service API
The Query Service provides a REST API that covers four requirements; which are the administration of Query Service nodes, the configuration of the Query Service, the execution of SQL++ statements, and the management of JavaScript libraries and objects used to create SQL++ user-defined functions. The REST API is detailed in the tables below.
Query Service Administration
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Query Service Settings
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Index Service API
The Index Service REST API provides configuration options for the Index Service. The API is listed below.
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Backup Service API
The Backup Service API supports management of the Backup Service, providing endpoints categorized as follows: Cluster, Configuration, Repository, Plan, Task, and Data.
All calls require the Full Admin role, and use port 8097.
Each URI, in Couchbase Server Enterprise Edition Version 7.0 and later, must be prefixed with /api/v1.
The individual endpoints are listed by category, in the tables below.
Configuration
| HTTP Method | URI | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Repository
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Plan
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Task
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
Search Service API
The Search Service allows users to create, manage, and query Full Text Indexes, whereby searches can be performed and matches attained on character strings. The Search Service REST API allows such indexes to be created and maintained. The API is listed in the tables below.
Index Definition
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Index Management
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
Index Monitoring and Debugging
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Index Querying
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
Node Configuration
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Node Diagnostics
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Node Monitoring
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
Index Partition Definition
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
Index Partition Querying
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
Eventing Service API
The Eventing Service REST API provides methods for working with Eventing Functions. The complete API is listed at Eventing REST API.
Analytics Service API
The Analytics Service provides a REST API for querying, configuration, and the management of links and libraries. The API is listed in the following tables.
Analytics Query API
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Analytics Admin API
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Analytics Config API
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Analytics Settings API
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
Analytics Links API
| HTTP Method | URI | Documented at |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
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. |