REST API overview

REST API overview

The Couchbase REST API enables you to manage a Couchbase Server deployment as well as perform operations such as storing design documents and querying for results. The REST API conforms to Representational State Transfer (REST) constraints, in other words, the REST API follows a RESTful architecture.

Use the REST API to manage clusters, server nodes, and buckets, and to retrieve run-time statistics within your Couchbase Server deployment. If you want to develop your own Couchbase-compatible SDK, you will also use the REST API 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 for example, are handled by Couchbase SDKs. See the Couchbase SDKs.

In addition, the Couchbase Web Console uses many of the same REST API endpoints that are used for a REST API request. This is especially for administrative tasks such as creating a new bucket, adding a node to a cluster, or changing cluster settings.

Please provide RESTful requests; you will not receive any handling instructions, resource descriptions, nor should you presume any conventions for URI structure for resources represented. The URIs in the REST API may have a specific URI or may even appear as RPC or some other architectural style using HTTP operations and semantics.

In other words, build your request starting from Couchbase Cluster URIs, and be aware that URIs for resources may change from version to version. Also note that the hierarchies shown here enable your reuse of requests, since they follow a similar pattern for accessing different parts of the system.

The REST API is built on a number of basic principles:

  • JSON Responses

    The Couchbase Management REST API returns many responses as JavaScript Object Notation (JSON). On that note, you may find it convenient to read responses in a JSON reader. Some responses may have an empty body, but indicate the response with standard HTTP codes. For more information, see RFC 4627 ( http://www.ietf.org/rfc/rfc4627.txt ) and www.json.org.

  • HTTP Basic Access Authentication

    The Couchbase Management REST API uses HTTP basic authentication. The browser-based Using the Web Console and Command-line Interface also 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 on any node in a cluster you want to access. If the server node cannot service a request directly, due to lack of access to state or some other information, it will forward the request to the appropriate server node, retrieve the results, and send the results back to the client.

In order to use the REST API you should be aware of the different terms and concepts discussed in the following sections.

Types of resources

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

Server nodes

A Couchbase Server instance, also known as ‘node’, is a physical or virtual machine running Couchbase Server. Each node is as a member of a cluster.

Cluster/Pool

A cluster is a group of one or more nodes; it 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 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 Management 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; therefore 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 overall system. Buckets are categorized by storage type: 1) memcached buckets are for in-memory, RAM-based information, and 2) Couchbase buckets, which 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. For more information, see Views and Indexes.

Cross datacenter replication (XDCR)

Cross Datacenter Replication (XDCR) is new functionality as of Couchbase Server 2.0. It enables you to automatically replicate data between clusters and between data buckets. There are two major benefits of using XDCR as part of your Couchbase Server implementation: 1) enables you to restore data from one Couchbase cluster to another cluster after system failure. 2) provide copies of data on clusters that are physically closer to your end users. For more information, see Cross Datacenter Replication (XDCR).

HTTP request headers

You will use the following HTTP request headers when you create your request:

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 hostname 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 status codes

The Couchbase Server will return one of the following HTTP status codes in response to your REST API request:

HTTP Status 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 you 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.

Clusters REST API

Clusters REST API

One of the first ways to discover the URI endpoints for the REST API is to find the clusters available. For this you provide the Couchbase Server IP address, port number, and append ‘/pools’.

Example Request

curl -u admin:password http://localhost:8091/pools

Replace the admin, password, and localhost values in the above example with your actual values.

As a raw HTTP request:

GET /pools
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1

The corresponding HTTP response contains a JSON document describing the cluster configuration:


HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn


{"pools": [
            {
            "name":"default",
            "uri":"/pools/default",
            "streamingUri":"/poolsStreaming/default"
            }
          ],
          "isAdminCreds":false,
          "uuid":"c25913df-59a2-4886-858c-7119d42e36ab",
          "implementationVersion":"1.8.1-927-rel-enterprise",
          "componentsVersion":
             {
             "ale":"8cffe61",
             "os_mon":"2.2.6",
             "mnesia":"4.4.19",
             "inets":"5.6",
             "kernel":"2.14.4",
             "sasl":"2.1.9.4",
             "ns_server":"1.8.1-927-rel-enterprise",
             "stdlib":"1.17.4"}
 }

Couchbase Server returns only one cluster per group of systems and the cluster will typically have a default name.

Couchbase Server returns the build number for the server in implementation_version, the specifications supported are in the componentsVersion. While this node can only be a member of one cluster, there is flexibility which allows for any given node to be aware of other pools.

The Client-Specification-Version is optional in the request, but advised. It allows for implementations to adjust representation and state transitions to the client, if backward compatibility is desirable.

Viewing cluster details

At the highest level, the response for this request describes a cluster, as mentioned previously. The response contains a number of properties which define attributes of the cluster and controllers which enable you to make certain requests of the cluster.

Warning

Since buckets could be renamed and there is no way to determine the name for the default bucket for a cluster, the system attempts to connect non-SASL, non-proxied to a bucket named "default". If it does not exist, Couchbase Server drops the connection.

Do not rely on the node list returned by this request to connect to a Couchbase Server. Instead, issue an HTTP Get call to the bucket to get the node list for that specific bucket.

GET /pools/default
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{
    "name":"default",
    "nodes":[{

        "hostname":"10.0.1.20",

        "status":"healthy",
        "uptime":"14",
        "version":"1.6.0",
        "os":"i386-apple-darwin9.8.0",
        "memoryTotal":3584844000.0,
        "memoryFree":74972000,
        "mcdMemoryReserved":64,
        "mcdMemoryAllocated":48,
        "ports":{

            "proxy":11213,
            "direct":11212
        },
        "otpNode":"ns_1@localhost",
        "otpCookie":"fsekryjfoeygvgcd",
        "clusterMembership":"active"
    }],
    "storageTotals":{

        "ram":{
            "total":2032558080,
            "used":1641816064

        },
        "hdd":{
            "total":239315349504.0,
            "used": 229742735523.0
        }
    },
    "buckets":{

        "uri":"/pools/default/buckets"
    },
    "controllers":{
        "ejectNode":{
            "uri":"/pools/default/controller/ejectNode"
        },
        "addNode":{


            "uri":"/controller/addNode"
        },
        "rebalance":{


            "uri":"/controller/rebalance"
        },
        "failover":{


            "uri":"/controller/failOver"
        },
        "reAddNode":{


            "uri":"/controller/reAddNode"
        },
        "stopRebalance":{


            "uri":"/controller/stopRebalance"
        }
    },
    "rebalanceProgress":{


        "uri":"/pools/default/rebalanceProgress"
    },
    "balanced": true,
    "etag":"asdas123",
    "initStatus":

    "stats":{
        "uri":"/pools/default/stats"
    }
}

The controllers in this list all accept parameters as x-www-form-urlencoded, and perform the following functions:

Function Description
ejectNode Eject a node from the cluster. Required parameter: “otpNode”, the node to be ejected.
addNode Add a node to this cluster. Required parameters: “hostname”, “user” and “password”. Username and password are for the Administrator for this node.
rebalance Rebalance the existing cluster. This controller requires both “knownNodes” and “ejectedNodes”. This allows a client to state the existing known nodes and which nodes should be removed from the cluster in a single operation. To ensure no cluster state changes have occurred since a client last got a list of nodes, both the known nodes and the node to be ejected must be supplied. If the list does not match the set of nodes, the request will fail with an HTTP 400 indicating a mismatch. Note rebalance progress is available via the rebalanceProgress uri.
failover Failover the vBuckets from a given node to the nodes which have replicas of data for those vBuckets. The “otpNode” parameter is required and specifies the node to be failed over.
reAddNode The “otpNode” parameter is required and specifies the node to be re-added.
stopRebalance Stop any rebalance operation currently running. This takes no parameters.

Adding nodes to clusters

This is a REST request made to a Couchbase cluster to add a given node to the cluster. You add a new node with the at the RESTful endpoint server_ip:port/controller/addNode. Provide an administrative username and password as parameters:

curl -u admin:password \
10.2.2.60:8091/controller/addNode \
-d "hostname=10.2.2.64&user=admin&password=password"

Here we create a request to the cluster at 10.2.2.60:8091 to add a given node by using method, controller/addNode and by providing the IP address for the node as well as credentials. Replace the admin, password, 10.2.2.60, and 10.2.2.64 values in the above example with your actual values.

If successful, Couchbase Server will respond:

HTTP/1.1 200 OK
{"otpNode":"ns_1@10.4.2.6"}

Joining nodes into clusters

This is a REST request made to an individual Couchbase node to add that node to a given cluster. You cannot merge two clusters together into a single cluster using the REST API, however, you can add a single node to an existing cluster. You will need to provide several parameters to add a node to a cluster:

curl -u admin:password -d clusterMemberHostIp=192.168.0.1 \
-d clusterMemberPort=8091 \
-d user=admin -d password=password
http://localhost:8091/node/controller/doJoinCluster

Replace the admin, password, and 192.168.0.1 values in the above example with your actual values.

The following arguments are required:

Argument | Description
——————–|———————————————————————————————– clusterMemberHostIp | Hostname or IP address to a member of the cluster the node receiving this POST will be joining clusterMemberPort | Port number for the RESTful interface to the system
If your cluster requires credentials, you will need to provide the following parameters in your request:

Argument Description
user Administration user
password Password associated with the Administration user
POST /node/controller/doJoinCluster
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxx
Accept: */*
Content-Length: xxxxxxxxxx
Content-Type: application/x-www-form-urlencoded
clusterMemberHostIp=192.168.0.1&clusterMemberPort=8091&user=admin&password=admin123
200 OK with Location header pointing to pool details of pool just joined - successful join
400 Bad Request - missing parameters, etc.
401 Unauthorized - credentials required, but not supplied
403 Forbidden bad credentials - invalid credentials

Removing nodes from clusters

When a node is temporarily or permanently down, you may want to remove it from a cluster:

curl -u admin:password -d otpNode=ns_1@192.168.0.107 \
http://192.168.0.106:8091/controller/ejectNode

Replace the admin, password, 192.168.0.107, and 192.168.0.106 values in the above example with your actual values.

POST /controller/ejectNode
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxx
Accept: */*
Content-Length: xxxxxxxxxx
Content-Type: application/x-www-form-urlencoded
otpNode=ns_1@192.168.0.1
200 OK - node ejected
400 Error, the node to be ejected does not exist
401 Unauthorized - Credentials were not supplied and are required
403 Forbidden - Credentials were supplied and are incorrect

Rebalancing nodes

To start a rebalance process through the REST API you must supply two arguments containing the list of nodes that have been marked to be ejected, and the list of nodes that are known within the cluster.

Initiating a rebalance

You can obtain the information about ejected and known node by getting the current node configuration from Managing Couchbase Nodes. This is to ensure that the client making the REST API request is aware of the current cluster configuration. Nodes should have been previously added or marked for removal as appropriate.

The information must be supplied via the ejectedNodes and knownNodes parameters as a POST operation to the /controller/rebalance endpoint.

Example

curl -v -X -u admin:password POST 'http://192.168.0.77:8091/controller/rebalance' \
-d 'ejectedNodes=&knownNodes=ns_1%40192.168.0.77%2Cns_1%40192.168.0.56'

Replace the admin, password, 192.168.0.77, and 192.168.0.56 values in the above example with your actual values.

The corresponding raw HTTP request:

POST /controller/rebalance HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: 192.168.0.77:8091
Accept: */*
Content-Length: 63
Content-Type: application/x-www-form-urlencoded

The response will be 200 (OK) if the operation was successfully submitted.

If the wrong node information has been submitted, JSON with the mismatch error will be returned:

{"mismatch":1}

Progress of the rebalance operation can be obtained by using Getting Rebalance Progress.

Getting Rebalance Progress

There are two endpoints for rebalance progress. One is a general request which outputs high-level percentage completion at /pools/default/rebalanceProgress. The second possible endpoint is one corresponds to the detailed rebalance report available in Web Console, see Monitoring a Rebalance for details and definitions.

Example

This first request returns a JSON structure containing the current progress information:

curl -u admin:password '192.168.0.77:8091/pools/default/rebalanceProgress'

Replace the admin, password, localhost, and 192.168.0.77 values in the above example with your actual values.

As a pure REST API call, it appears as follows:

GET /pools/default/rebalanceProgress HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: 192.168.0.77:8091
Accept: */*

The response data packet contains a JSON structure showing the rebalance progress for each node. The progress figure is provided as a percentage (shown as a floating point value between 0 and 1).

{
    "status":"running",
    "ns_1@192.168.0.56":{"progress":0.2734375},
    "ns_1@192.168.0.77":{"progress":0.09114583333333337}
}

For more details about the rebalance, use the following request:

curl -u admin:password 'http://localhost:8091/pools/default/tasks'

Replace the admin, password, and localhost values in the above example with your actual values.

GET /pools/default/rebalanceProgress HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: 192.168.0.77:8091
Accept: */*

The response data packet contains a JSON structure showing detailed progress:


{
  type: "rebalance",
  recommendedRefreshPeriod: 0.25,
  status: "running",
  progress: 9.049479166666668,
  perNode: {
    ns_1@10.3.3.61: {
      progress: 13.4765625
    },
    ns_1@10.3.2.55: {
      progress: 4.6223958333333375
    }
  },
  detailedProgress: {
    bucket: "default",
    bucketNumber: 1,
    bucketsCount: 1,
    perNode: {
      ns_1@10.3.3.61: {
        ingoing: {
          docsTotal: 0,
          docsTransferred: 0,
          activeVBucketsLeft: 0,
          replicaVBucketsLeft: 0
        },
        outgoing: {
          docsTotal: 512,
          docsTransferred: 69,
          activeVBucketsLeft: 443,
          replicaVBucketsLeft: 511
        }
      },
      ns_1@10.3.2.55: {
        ingoing: {
          docsTotal: 512,
          docsTransferred: 69,
          activeVBucketsLeft: 443,
          replicaVBucketsLeft: 0
        },
        outgoing: {
          docsTotal: 0,
          docsTransferred: 0,
          activeVBucketsLeft: 0,
          replicaVBucketsLeft: 443
        }
      }
    }
  }
}

This shows percentage complete for each individual node undergoing rebalance. For each specific node, it provides the current number of docs transferred and other items. For details and definitions of these items, see Monitoring a Rebalance.

If you rebalance fails, you will see this response:

[
  {
    "type": "rebalance",
    "status": "notRunning",
    "errorMessage": "Rebalance failed. See logs for detailed reason. You can try rebalance again."
  }
]

Adjusting Rebalance during Compaction

If you perform a rebalance while a node is undergoing index compaction, you may experience delays in rebalance. There is REST API parameter as of Couchbase Server 2.0.1 you can use to improve rebalance performance. If you do make this selection, you will reduce the performance of index compaction which can result in larger index file size.

Example

To make this request:

curl -X POST -u admin:password 'http://localhost:8091/internalSettings' 
    -d 'rebalanceMovesBeforeCompaction=256'

Replace the admin, password, localhost, and 256 values in the above example with your actual values.

This needs to be made as POST request to the /internalSettings endpoint. By default this setting is 16, which specifies the number of vBuckets which will moved per node until all vBucket movements pauses. After this pause the system triggers index compaction. Index compaction will not be performed while vBuckets are being moved, so if you specify a larger value, it means that the server will spend less time compacting the index, which will result in larger index files that take up more disk space.

Managing auto-failover

This section provides information about retrieving, enabling, disabling and resetting auto-failover.

Retrieving auto-failover settings

Use this request to retrieve any auto-failover settings for a cluster. Auto-failover is a global setting for all clusters. You need to be authenticated to read this value. Example:

curl -u admin:password http://localhost:8091/settings/autoFailover

Replace the admin, password, and localhost values in the above example with your actual values.

If successful Couchbase Server returns any auto-failover settings for the cluster:

{"enabled":false,"timeout":30,"count":0}

The following parameters and settings appear:

  • enabled : either true if auto-failover is enabled or false if it is not.

  • timeout : seconds that must elapse before auto-failover executes on a cluster.

  • count : can be 0 or 1. Number of times any node in a cluster can be automatically failed-over. After one auto-failover occurs, count is set to 1 and Couchbase server will not perform auto-failure for the cluster again unless you reset the count to 0. If you want to failover more than one node at a time in a cluster, you will need to do so manually.

Possible errors include:

HTTP/1.1 401 Unauthorized
This endpoint isn't available yet.
GET /settings/autoFailover HTTP/1.1
Host: localhost:8091
Authorization: Basic YWRtaW46YWRtaW4=
Accept: */*
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{ "enabled": false, "timeout": 30, "count": 0 }

Enabling and disabling auto-failover

This is a global setting you apply to all clusters. You need to be authenticated to change this value. An example of this request:

curl "http://localhost:8091/settings/autoFailover" \
    -i -u admin:password -d 'enabled=true&timeout=600'

Replace the admin, password, localhost, and 600 values in the above example with your actual values.

Possible parameters are:

  • enabled (true|false) (required): Indicates whether Couchbase Server will perform auto-failover for the cluster or not.

  • timeout (integer that is greater than or equal to 30) (required; optional when enabled=false): The number of seconds a node must be down before Couchbase Server performs auto-failover on the node.

POST /settings/autoFailover HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: 14
enabled=true&timeout=60
HTTP/1.1 200 OK

The possible errors include:

400 Bad Request, The value of "enabled" must be true or false.
400 Bad Request, The value of "timeout" must be a positive integer bigger or equal to 30.
401 Unauthorized
This endpoint isn't available yet.

Resetting auto-failover

This resets the number of nodes that Couchbase Server has automatically failed-over. You can send a request to set the auto-failover number to 0. This is a global setting for all clusters. You need to be authenticated to change this value. No parameters are required:

curl -X POST -i -u admin:password \
    http://localhost:8091/settings/autoFailover/resetCount

Replace the admin, password, and localhost values in the above example with your actual values.

POST /settings/autoFailover/resetCount HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
HTTP/1.1 200 OK

Possible errors include:

This endpoint isn't available yet.
401 Unauthorized

Setting maximum buckets for clusters

By default the maximum number of buckets recommended for a Couchbase Cluster is ten. This is a safety mechanism to ensure that a cluster does not have resource and CPU overuse due to too many buckets. This limit is configurable using the REST API.

The Couchbase REST API has changed to enable you to change the default maximum number of buckets used in a Couchbase cluster. The maximum allowed buckets in this request is 128, however the suggested maximum number of buckets is ten per cluster. The following illustrates the endpoint and parameters used:

curl -X POST -u admin:password -d maxBucketCount=6 http://localhost:8091/internalSettings

Replace the admin, password, localhost, and 6 values in the above example with your actual values.

For this request you need to provide administrative credentials for the cluster. The following HTTP request will be sent:

About to connect() to 127.0.0.1 port 8091 (#0)
Trying 127.0.0.1...
connected
Connected to 127.0.0.1 (127.0.0.1) port 8091 (#0)
Server auth using Basic with user 'Administrator'
POST /internalSettings HTTP/1.1

If Couchbase Server successfully changes the bucket limit for the cluster, you will get a HTTP 200 response:

HTTP/1.1 200 OK
Server: Couchbase Server 2.0.0r_501_gb614829
Pragma: no-cache
Date: Wed, 31 Oct 2012 21:21:48 GMT
Content-Type: application/json
Content-Length: 2
Cache-Control: no-cache

If you provide an invalid number, such as 0, a negative number, or an amount over 128 buckets, you will get this error message:

["Unexpected server error, request logged."]

Setting maximum parallel indexers

You can set the number of parallel indexers that will be used on each node when view indexes are updated. To get the current setting of the number of parallel indexers, use a GET request.

Get Maximum Parallel Indexers Description
Method GET /settings/maxParallelIndexers
Request Data None
Response Data JSON of the global and node-specific parallel indexer configuration
Authentication Required no

For example:

GET http://127.0.0.1:8091/settings/maxParallelIndexers

This returns a JSON structure of the current settings, providing both the globally configured value, and individual node configuration:

{
   "globalValue" : 4,
   "nodes" : {
      "ns_1@127.0.0.1" : 4
   }
}

To set the value, POST to the URL specifying a URL-encoded value to the globalValue argument.

Set Maximum Parallel Indexers Description
Method POST /settings/maxParallelIndexers
Request Data None
Response Data JSON of the global and node-specific parallel indexer configuration
Authentication Required yes
Payload Arguments
globalValue Required parameter. Numeric. Sets the global number of parallel indexers. Minimum of 1, maximum 1024.
Return Codes
400 globalValue not specified or invalid

View settings for email notifications

The response to this request will specify whether you have email alerts set, and which events will trigger emails. This is a global setting for all clusters. You need to be authenticated to read this value:

curl -u admin:password http://localhost:8091/settings/alerts

Replace the admin, password, and localhost values in the above example with your actual values.

GET /settings/alerts HTTP/1.1
Host: localhost:8091
Authorization: Basic YWRtaW46YWRtaW4= Accept: */*
{
    "recipients": ["root@localhost"],
    "sender":"couchbase@localhost",
    "enabled":true,
    "emailServer":{"user":"","pass":"","host":"localhost","port":25,"encrypt":false},
    "alerts":
      ["auto_failover_node",
      "auto_failover_maximum_reached",
      "auto_failover_other_nodes_down",
      "auto_failover_cluster_too_small"]
  }

Possible errors include:

This endpoint isn't available yet.

Enabling and disabling email notifications

This is a global setting for all clusters. You need to be authenticated to change this value. If this is enabled, Couchbase Server sends an email when certain events occur. Only events related to auto-failover trigger notification:

curl -i -u admin:password \
    -d 'enabled=true&sender=couchbase@localhost&recipients=admin@localhost,membi@localhost&emailHost=localhost&emailPort=25&emailEncrypt=false' http://localhost:8091/settings/alerts

Replace the admin, password, localhost, couchbase@localhost, admin@localhost, membi@localhost, 25, and false values in the above example with your actual values.

Possible parameters include:

  • enabled : (true|false) (required). Whether to enable or disable email notifications

  • sender (string) (optional, default: couchbase@localhost). Email address of the sender.

  • recipients (string) (required). A comma separated list of recipients of the of the emails.

  • emailHost (string) (optional, default: localhost). Host address of the SMTP server

  • emailPort (integer) (optional, default: 25). Port of the SMTP server

  • emailEncrypt (true|false) (optional, default: false). Whether you want to use TLS or not

  • emailUser (string) (optional, default: “”): Username for the SMTP server

  • emailPass (string) (optional, default: “”): Password for the SMTP server

  • alerts (string) (optional, default: auto_failover_node, auto_failover_maximum_reached, auto_failover_other_nodes_down, auto_failover_cluster_too_small). Comma separated list of alerts that should cause an email to be sent. Possible values are: auto_failover_node, auto_failover_maximum_reached, auto_failover_other_nodes_down, auto_failover_cluster_too_small.

POST /settings/alerts HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: 14 enabled=true&sender=couchbase@localhost&recipients=admin@localhost,membi@localhost&emailHost=localhost&emailPort=25&emailEncrypt=false�
HTTP/1.1 200 OK

Possible HTTP errors include:

400 Bad Request
401 Unauthorized
JSON object ({"errors": {"key": "error"}}) with errors.
  • Possible errors returned in a JSON document include:

  • alerts: alerts contained invalid keys. Valid keys are: [list_of_keys].

  • email_encrypt: emailEncrypt must be either true or false.

  • email_port: emailPort must be a positive integer less than 65536.

  • enabled: enabled must be either true or false.

  • recipients: recipients must be a comma separated list of valid email addresses.

  • sender: sender must be a valid email address.

  • general: No valid parameters given.

Sending test emails

This is a global setting for all clusters. You need to be authenticated to change this value. In response to this request, Couchbase Server sends a test email with the current configurations. This request uses the same parameters used in setting alerts and additionally an email subject and body.

curl -i -u admin:password http://localhost:8091/settings/alerts/testEmail \
    -d 'subject=Test+email+from+Couchbase& \
    body=This+email+was+sent+to+you+to+test+the+email+alert+email+server+settings.&enabled=true& \
    recipients=vmx%40localhost&sender=couchbase%40localhost& \
    emailUser=&emailPass=&emailHost=localhost&emailPort=25&emailEncrypt=false& \
    alerts=auto_failover_node%2Cauto_failover_maximum_reached%2Cauto_failover_other_nodes_down%2Cauto_failover_cluster_too_small'

Replace the admin, password, localhost, vmx%40localhost, couchbase%40localhost, 25, and false values in the above example with your actual values.

POST /settings/alerts/sendTestEmail HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=

200 OK

Possible errors include:

400 Bad Request: Unknown macro: {"error"} 401 Unauthorized
This endpoint isn't available yet.

Managing internal cluster settings

You can set a number of internal settings the number of maximum number of supported buckets supported by the cluster. To get the current setting of the number of parallel indexers, use a GET request.

Get Internal Settings Description
Method GET /internalSettings
Request Data None
Response Data JSON of current internal settings
Authentication Required no
Return Codes
200 Settings returned

For example:

GET http://127.0.0.1:8091/internalSettings

This returns a JSON structure of the current settings:

{
  "indexAwareRebalanceDisabled":false,
  "rebalanceIndexWaitingDisabled":false,
  "rebalanceIndexPausingDisabled":false,
  "maxParallelIndexers":4,
  "maxParallelReplicaIndexers":2,
  "maxBucketCount":20
}

To set a configuration value, POST to the URL a payload containing the updated values.

Set Configuration Value Description
Method POST /settings/maxParallelIndexers
Request Data None
Response Data JSON of the global and node-specific parallel indexer configuration
Authentication Required yes
Payload Arguments
globalValue Required parameter. Numeric. Sets the global number of parallel indexers. Minimum of 1, maximum 1024.
Return Codes
400 globalValue not specified or invalid

For example, to update the maximum number of buckets:

curl -v -X POST http://admin:password@localhost:8091/internalSettings \
-d maxBucketCount=20

Replace the admin, password, localhost, and 20 values in the above example with your actual values.

Disabling consistent query results on rebalance

If you perform queries during rebalance, this new feature will ensure that you receive the query results that you would expect from a node as if it is not being rebalanced. During node rebalance, you will get the same results you would get as if the data were on an original node and as if data were not being moved from one node to another. In other words, this new feature ensures you get query results from a new node during rebalance that are consistent with the query results you would have received from the node before rebalance started.

By default this functionality is enabled; although it is possible to disable this functionality via the REST API, under certain circumstances described below.

Note

Be aware that rebalance may take significantly more time if you have implemented views for indexing and querying. While this functionality is enabled by default, if rebalance time becomes a critical factor for your application, you can disable this feature via the REST API.

We do not recommend you disable this functionality for applications in production without thorough testing. To do so may lead to unpredictable query results during rebalance.

To disable this feature, provide a request similar to the following:

curl -v -u admin:password -X POST http://localhost:8091/internalSettings \
-d indexAwareRebalanceDisabled=true

Replace the admin, password, and localhost values in the above example with your actual values.

If successful Couchbase Server will send a response:

HTTP/1.1 200 OK
Content-Type: application/json

For more information about views and how they function within a cluster, see View Operation.

Server nodes REST API

A Couchbase Server instance, also known as ‘node’, is a physical or virtual machine running Couchbase Server. Each node is as a member of a cluster.

To view information about nodes that exist in a Couchbase Cluster, you use this request:

curl -u admin:password http://localhost:8091/pools/nodes

Replace admin, password, and localhost values in the above example with your actual values.

Couchbase server returns this response in JSON:

{"storageTotals":
                    {
                    "ram":
                    {
                    "quotaUsed":10246684672.0,
                    "usedByData":68584936,
                    "total":12396216320.0,
                    "quotaTotal":10246684672.0,
                    "used":4347842560.0},
                    "hdd":
                          {"usedByData":2560504,
                          "total":112654917632.0,
                          "quotaTotal":112654917632.0,
                          "used":10138942586.0,
                          "free":102515975046.0}
                     },
                     "name":"nodes",
                     "alerts":[],
                     "alertsSilenceURL":"/controller/resetAlerts?token=0",
                     "nodes":
                            [{"systemStats":
                                      {
                                      "cpu_utilization_rate":2.5,
                                      "swap_total":6140452864.0,
                                      "swap_used":0
                                      },
                             "interestingStats":
                                      {
                                      "curr_items":0,
                                      "curr_items_tot":0,
                                      "vb_replica_curr_items":0
                                      },
                              "uptime":"5782",
                              "memoryTotal":6198108160.0,
                              "memoryFree":3777110016.0,
                              "mcdMemoryReserved":4728,
                              "mcdMemoryAllocated":4728,
                              "clusterMembership":"active",
                              "status":"healthy",
                              "hostname":"10.4.2.5:8091",
                              "clusterCompatibility":1,
                              "version":"1.8.1-937-rel-community",
                              "os":"x86_64-unknown-linux-gnu",
                              "ports":
                                      {
                                      "proxy":11211,
                                      "direct":11210
                                      }
                            .......

                                  }],
                       "buckets":
                                {"uri":"/pools/nodes/buckets?v=80502896" },
                                "controllers":{"addNode":{"uri":"/controller/addNode"},
                                "rebalance":{"uri":"/controller/rebalance"},
                                "failOver":{"uri":"/controller/failOver"},
                                "reAddNode":{"uri":"/controller/reAddNode"},
                                "ejectNode":{"uri":"/controller/ejectNode"},
                                "testWorkload":{"uri":"/pools/nodes/controller/testWorkload"}},
                                "balanced":true,
                                "failoverWarnings":["failoverNeeded","softNodesNeeded"],
                                "rebalanceStatus":"none",
                                "rebalanceProgressUri":"/pools/nodes/rebalanceProgress",
                                "stopRebalanceUri":"/controller/stopRebalance",
                                "nodeStatusesUri":"/nodeStatuses",
                                "stats":{"uri":"/pools/nodes/stats"},
                                "counters":{"rebalance_success":1,"rebalance_start":1},
                                "stopRebalanceIsSafe":true}

Retrieving statistics

To retrieve statistics about a node, you can first retrieve a list of nodes in a cluster with this request:

curl -u admin:password http://localhost:8091/pools/default/buckets/default/nodes

Replace the admin, password, and values in the above example with your actual values.

You can send this request using the IP address and port for any node in the cluster. This sends the following HTTP request:

GET /pools/default/buckets/default/nodes HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*

If Couchbase Server successfully handles the request, you will get a response similar to the following example:

{"servers":[
  {"hostname":"10.4.2.6:8091",
  "uri":"/pools/default/buckets/default/nodes/10.4.2.6%3A8091",
  "stats":
      {"uri":"/pools/default/buckets/default/nodes/10.4.2.6%3A8091/stats"}}
    ....

You can then make a REST request to the specific IP address and port of given node shown in the response and add /stats as the endpoint:

curl -u admin:password http://10.4.2.4:8091/pools/default/buckets/default/nodes/10.4.2.4%3A8091/stats

Replace the admin, password, and 10.4.2.4 values in the above example with your actual values.

This sends the following HTTP request:

GET /pools/default/buckets/default/nodes/10.4.2.4%3A8091/stats HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*

If Couchbase Server successfully handles the request, you will get a response similar to the following example:

{"hostname":"10.4.2.4:8091","hot_keys":[{"name":"[2012-11-05::3:47:01]"
....
"samplesCount":60,"isPersistent":true,"lastTStamp":1352922180718,"interval":1000}}

The statistics returned will be for the individual bucket associated with that node.

Provisioning nodes

Creating a new cluster or adding a node to a cluster is called provisioning. You need to:

  • Create a new node by installing a new Couchbase Server.

  • Configure disk path for the node.

  • Optionally configure memory quota for each node within the cluster. Any nodes you add to a cluster will inherit the configured memory quota. The default memory quota for the first node in a cluster is 60% of the physical RAM.

  • Add the node to your existing cluster.

Whether you are adding a node to an existing cluster or starting a new cluster, the node’s disk path must be configured. Your next steps depends on whether you create a new cluster or you want to add a node to an existing cluster. If you create a new cluster you will need to secure it by providing an administrative username and password. If you add a node to an existing cluster you will need the URI and credentials to use the REST API with that cluster.

Configuring index paths

The path for the index files can be configured through the use of the index_path parameter:

Example as follows:

curl -X POST -u admin:password \
-d index_path=/var/tmp/text-index \
http://localhost:8091/nodes/self/controller/settings

Replace the admin, password, localhost, and /var/tmp/text-index values in the above example with your actual values.

As a raw HTTP request:

POST /nodes/self/controller/settings HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx path=/var/tmp/test

The HTTP response will contain the response code and optional error message:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0

As of Couchbase Server 2.0.1 if you try to set the data path at this endpoint, you will receive this error:

ERROR: unable to init 10.3.4.23 (400) Bad Request
{u'error': u'Changing data of nodes that are part of provisioned cluster is not supported'}

Setting usernames and passwords

While this can be done at any time for a cluster, it is typically the last step you complete when you add node into being a new cluster. The response will indicate the new base URI if the parameters are valid. Clients will want to send a new request for cluster information based on this response.

For example, using curl :

curl -u admin:password -d username=Administrator \
-d password=letmein \
-d port=8091 \
http://localhost:8091/settings/web

Replace the admin, password, localhost, letmein, and Administrator values in the above example with your actual values.

The raw HTTP request:

POST /settings/web HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
username=Administrator&password=letmein&port=8091

The corresponding HTTP response data:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Couchbase Server 2.0
Pragma: no-cache
Date: Mon, 09 Aug 2010 18:50:00 GMT
Content-Type: application/json
Content-Length: 39
Cache-Control: no-cache no-store max-age=0
{"newBaseUri":"http://localhost:8091/"}

Note

The port number must be specified when username/password is updated.

Configuring node memory quota

The node memory quota configures how much RAM to be allocated to Couchbase for every node within the cluster.

Set Memory Description
Method POST /pools/default
Request Data Payload with memory quota setting
Response Data Empty
Authentication Required yes
Return Codes
200 OK
400 Bad Request JSON: The RAM Quota value is too small.
401 Unauthorized

For example, to set the memory quota for a cluster at 400MB:

curl -X POST -u admin:password -d memoryQuota=400 http://localhost:8091/pools/default

Replace the admin, password, localhost, and 400 values in the above example with your actual values.

As a raw HTTP request:

POST /pools/default HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
memoryQuota=400

The HTTP response will contain the response code and optional error message:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0

Providing hostnames

There are several ways you can provide hostnames for Couchbase. You can provide a hostname when you install a Couchbase Server node, when you add it to an existing cluster for online upgrade, or via a REST API call. If a node restarts, any hostname you establish will be used. You cannot provide a hostname for a node that is already part of a Couchbase cluster; the server will reject the request and return error 400 reason: unknown ["Renaming is disallowed for nodes that are already part of a cluster"].

To see the specific REST request, see Using hostnames.

Requesting node failover

You can use this request to failover a node in the cluster. When you failover a node, it indicates the node is no longer available in a cluster and replicated data at another node should be available to clients. You can also choose to perform node failover using the Web Console.

Using the REST API endpoint host:port/controller/failOver, provide your administrative credentials and the parameter optNode which is an internal name for the node:

curl -v -X POST -u admin:password http://localhost:8091/controller/failOver -d otpNode=ns_2@10.3.3.63

Replace the admin, password, localhost, and 10.3.3.63, values in the above example with your actual values.

The HTTP request will be similar to the following:

POST /controller/failOver HTTP/1.1
Authorization: Basic

Upon success, Couchbase Server will send a response as follows:

HTTP/1.1 200 OK

If you try to failover a node that does not exist in the cluster, you will get a HTTP 404 error. To learn more about how to retrieve optNode information for the nodes in a cluster, see Managing Clusters.

Rack Awareness REST API

Rack Awareness REST API

The Rack Awareness feature allows logical groupings of servers on a cluster where each server group physically belongs to a rack or availability zone. This feature provides the ability to specify that active and corresponding replica partitions be created on servers that are part of a separate rack or zone. For purposes of the server group REST API, racks or availability zones are represented as flat space of server groups with group names. To enable Rack Awareness, all servers in a cluster must be upgraded to use the Rack Awareness feature.

Note

The Rack Awareness feature with its server group capability is an Enterprise Edition feature.

The Server groups REST API provides the following capability:

  • Creates server groups
  • Edits server groups
  • Deletes server groups
  • Assigns servers to server groups.

HTTP Methods

The following summarizes the HTTP methods used for managing server groups.

HTTP method URI path Description
GET /pools/default/serverGroups Retrieves information about a server group.
POST /pools/default/serverGroups Creates a server group with a specific name.
PUT /pools/default/serverGroups/<:uuid> Updates the server group information.
PUT /pools/default/serverGroups?rev=<:number> Updates a server’s group memberships.
DELETE /pools/default/serverGroups/<:uuid> Deletes a specific server group.

Retrieving server group information

GET /pools/default/serverGroups retrieves information about server groups. Provides group information, "groups": [(<groupInfo>)+], where each server group has unique URIs and UUIDs.

Syntax

curl -X GET -u <administrator>:<password> 
   http://<host>:<port>/pools/default/serverGroups

Example

curl -X GET -u Admin:myPassword 
   http://192.168.0.1:8091/pools/default/serverGroups

Returns

{"groups":
   [
      {
      "name":"<groupName>", 
      "uri": "/pools/default/serverGroups?rev=<integer>",
      "addNodeURI":"/pools/default/serverGroups/0",
      "nodes":[(<nodeInfo>)+]
      }
    ]
}
Group info Description
"groups": [(<groupInfo>)+] Information about server groups.
"name":"<groupName>" Specifies the name of the group. If the group name has a space, for example, Group A, use double quotes (for example, "Group A"). If the name does not have spaces (for example, GroupA) double quotes are not required.
"uri":"/pools/default/serverGroups?rev=<integer>" Specifies the URI path and revision integer.
"uri":"/pools/default/serverGroups/<:uuid>" Specifies the URI path and UUID string.
"addNodeURI":"/pools/default/serverGroups/<:uuid>/addNode Specifies the URI path and UUID string for adding servers to a server group.
"nodes": [(<nodeInfo>+)] Information about the servers.

Creating server groups

POST /pools/default/serverGroups creates a server group with a specific name. In the following example, Group A is created. If the group name has a space, for example, Group A, use double quotes; for example, "Group A".

Syntax

curl -X POST -u <administrator>:<password> 
  http://<host>:<port>/pools/default/serverGroups 
  -d name="<groupName>"

Example

curl -X POST -u Admin:myPassword 
  http://192.168.0.1:8091/pools/default/serverGroups 
  -d name="Group A"

Renaming server groups

PUT /pools/default/serverGroups/<:uuid> renames the server group. Find the UUID for the server group by using GET, add the UUID to the URI path, and specify a new group name. In this example, Group A is renamed to Group B. The UUID for the server group is located in the full URI information for that server group. The UUID remains the same for the server group after changing the name.

For example, the UUID for Group A is located in the following group information:

"name":"Group A",
"uri":"/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a"

Syntax

curl -X PUT -u <administrator>:<password> 
  http://<host>:<port>/pools/default/serverGroups/<uuid> 
  -d name="<newGroupName>"

Example

curl -X PUT -u Admin:myPassword 
  http://192.168.0.1:8091/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a 
  -d name="Group B"

Deleting server groups

DELETE /pools/default/serverGroups/<:uuid> deletes a specific server group. The server group must be empty for a successful request. In the following example, the UUID is the same UUID used in the renaming example.

Syntax

curl -X DELETE -u <administrator>:<password> 
  http://<host>:<port>/pools/default/serverGroups/<uuid>

Example

curl -X DELETE -u Admin:myPassword 
  http://192.168.0.1:8091/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a

Adding servers to server groups

POST /pools/default/serverGroups/<:uuid>/addNode adds a server to a cluster and assigns it to the specified server group.

Syntax

curl -X POST -dhostname=<host>:<port> 
  -u <administrator>:<password> 
  http://<host>:<port>/pools/default/serverGroups/<uuid>/addNode

Example

curl -X POST -dhostname=192.168.0.2:8091 
  -u Admin:myPassword 
  http://192.168.0.1:8091/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a/addNode

The server group’s UUID is in the group information

"name":"Group 2",
"uri":"/pools/default/serverGroups/d55339548767ceb51b241c61e3b9f036",
"addNodeURI":"/pools/default/serverGroups/d55339548767ceb51b241c61e3b9f036/addNode",

Updating server group memberships

PUT /pools/default/serverGroups?rev=<:number> updates the server’s group memberships. In the following examples, the group name is optional. If the group name is provided, it must match the current group name. All servers must be mentioned and all groups must be mentioned. The URI is used to identify the group.

This request only allows moving servers between server groups. It does not allow server group renaming or removal. In this example, the servers for Group 2 are moved to Group 1.

The following is the group information that is needed to update the server and server group memberships:

{
   "groups": [( { ("name": <groupName:string>,)? 
   "uri": "/pools/default/serverGroups/"<uuid>,
   "nodes": [(<otpNode>)*]
}

Syntax

curl -d @<inputFile> -X PUT 
  -u <administrator>:<password> 
  http://<host>:<port>/pools/default/serverGroups?rev=<number>

Example

In this example, a JSON file is used.

curl -d@file.json -X PUT 
  http://Administrator:asdasd@192.168.0.1:8091/pools/default/serverGroups?rev=120137811

Example

In this example, the JSON data is provided on the command line.


curl -v -X PUT 
  -u Administrator:password 
  http://192.168.171.144:8091/pools/default/serverGroups?rev=28418649 
  -d '{"groups":
      [{"nodes": [{"otpNode": "ns_1@192.168.171.144"},
                  {"otpNode": "ns_1@192.168.171.145"}], 
        "name": "Group 1", 
        "uri": "/pools/default/serverGroups/0"}, 
       {"nodes": [], 
        "name": "Group 2", 
        "uri": "/pools/default/serverGroups/3ca074a8456e1d4940cfa3b7badc1e22"}] }'

Note

The PUT request is transactional. The request either succeeds completely or fails without impact. If all nodes or groups are not passed, a generic error message: "Bad input" occurs and the server group is removed.

Buckets REST API

Buckets REST API

The bucket management and configuration REST API endpoints are provided to fine level control over the individual buckets in the cluster, their configuration, and specific operations such as FLUSH.

HTTP method URI path Description
GET /pools/default/buckets Retrieves all bucket and bucket operations information from a cluster.
GET /pools/default/buckets/default Retrieves information for a single bucket associated with a cluser.
GET /pools/default/buckets/bucket_name/stats Retrieves bucket statistics for a specific bucket.
POST /pools/default/buckets Creates a new Couchbase bucket.
DELETE /pools/default/buckets/bucket_name Deletes a specific bucket.
POST /pools/default/buckets/default/controller/doFlush Flushes a specific bucket.

Viewing buckets and bucket operations

If you create your own SDK for Couchbase, you can use either the proxy path or the direct path to connect to Couchbase Server. If your SDK uses the direct path, your SDK will not be insulated from most reconfiguration changes to the bucket. This means your SDK will need to either poll the bucket’s URI or connect to the streamingUri to receive updates when the bucket configuration changes. Bucket configuration can happen for instance, when nodes are added, removed, or if a node fails.

To retrieve information for all bucket for cluster:

curl -u admin:password http://localhost:8091/pools/default/buckets

Replace the admin, password, and localhost values in the above example with your actual values.

GET /pools/default/buckets
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
HTTP/1.1 200 OK
Server: Couchbase Server 1.6.0
Pragma: no-cache
Date: Wed, 03 Nov 2010 18:12:19 GMT
Content-Type: application/json
Content-Length: nnn
Cache-Control: no-cache no-store max-age=0
[
    {
        "name": "default",
        "bucketType": "couchbase",
        "authType": "sasl",
        "saslPassword": "",
        "proxyPort": 0,
        "uri": "/pools/default/buckets/default",
        "streamingUri": "/pools/default/bucketsStreaming/default",
        "flushCacheUri": "/pools/default/buckets/default/controller/doFlush",
        "nodes": [
            {
                "uptime": "784657",
                "memoryTotal": 8453197824.0,
                "memoryFree": 1191157760,
                "mcdMemoryReserved": 6449,
                "mcdMemoryAllocated": 6449,
                "clusterMembership": "active",
                "status": "unhealthy",
                "hostname": "10.1.15.148:8091",
                "version": "1.6.0",
                "os": "windows",
                "ports": {
                    "proxy": 11211,
                    "direct": 11210
                }
            }
        ],
        "stats": {
            "uri": "/pools/default/buckets/default/stats"
        },
        "nodeLocator": "vbucket",
        "vBucketServerMap": {
            "hashAlgorithm": "CRC",
            "numReplicas": 1,
            "serverList": [
                "192.168.1.2:11210"
            ],
      "vBucketMap": [ [ 0, -1 ], [ 0, -1 ], [ 0, -1 ], [ 0, -1 ], [ 0, -1 ], [ 0, -1 ]]
  },
        "replicaNumber": 1,
        "quota": {
            "ram": 104857600,
            "rawRAM": 104857600
        },
        "basicStats": {
            "quotaPercentUsed": 24.360397338867188,
            "opsPerSec": 0,
            "diskFetches": 0,
            "itemCount": 0,
            "diskUsed": 0,
            "memUsed": 25543728
        }
    },
    {
        "name": "test-application",
        "bucketType": "memcached",
        "authType": "sasl",
        "saslPassword": "",
        "proxyPort": 0,
        "uri": "/pools/default/buckets/test-application",
        "streamingUri": "/pools/default/bucketsStreaming/test-application",
        "flushCacheUri": "/pools/default/buckets/test-application/controller/doFlush",
        "nodes": [
            {
                "uptime": "784657",
                "memoryTotal": 8453197824.0,
                "memoryFree": 1191157760,
                "mcdMemoryReserved": 6449,
                "mcdMemoryAllocated": 6449,
                "clusterMembership": "active",
                "status": "healthy",
                "hostname": "192.168.1.2:8091",
                "version": "1.6.0",
                "os": "windows",
                "ports": {
                    "proxy": 11211,
                    "direct": 11210
                }
            }
        ],
        "stats": {
            "uri": "/pools/default/buckets/test-application/stats"
        },
        "nodeLocator": "ketama",
        "replicaNumber": 0,
        "quota": {
            "ram": 67108864,
            "rawRAM": 67108864
        },
        "basicStats": {
            "quotaPercentUsed": 4.064150154590607,
            "opsPerSec": 0,
            "hitRatio": 0,
            "itemCount": 1385,
            "diskUsed": 0,
            "memUsed": 2727405
        }
    }
]

Getting single bucket information

To retrieve information for a single bucket associated with a cluster, you make this request, where the last default can be replaced with the name of a specific bucket, if you have named buckets:

curl -u admin:password \
http://localhost:8091/pools/default/buckets/default

Replace the admin, password, and localhost values in the above example with your actual values.

Couchbase Server returns a large JSON document with bucket information including internal vBucket information:

{
    "name":"default",
    "bucketType":"membase",
    "authType":"sasl",
    "saslPassword":"",
    "proxyPort":0,
    "uri":"/pools/default/buckets/default",
    "streamingUri":"/pools/default/bucketsStreaming/default",
    "flushCacheUri":"/pools/default/buckets/default/controller/doFlush",
    "nodes":[
        {
            "systemStats":
            {
                "cpu_utilization_rate":1.5151515151515151,
                "swap_total":6140452864.0,
                "swap_used":0
            },

                ......

            "replicaNumber":1,
            "quota":
            {
                "ram":10246684672.0,
                "rawRAM":5123342336.0
            },
            "basicStats":
            {
                "quotaPercentUsed":0.5281477251650123,
                "opsPerSec":0,"diskFetches":0,
                "itemCount":0,
                "diskUsed":7518856,
                "memUsed":54117632
            }
        }
    ]
}
GET http://10.4.2.5:8091/pools/default/buckets/default?_=1340926633052
HTTP/1.1 200 OK

Getting bucket statistics

You can use the REST API to get statistics at the bucket level from Couchbase Server. Your request URL should be taken from stats.uri property of a bucket response. By default this request returns stats samples for the last minute and for heavily used keys. You use provide additional query parameters in a request to get a more detailed level of information:

  • zoom - provide statistics sampling for that bucket stats at a particular interval (minute | hour | day | week | month | year). For example zoom level of minute will provide bucket statistics from the past minute, a zoom level of day will provide bucket statistics for the past day, and so on. If you provide no zoom level, the server returns samples from the past minute.

  • haveTStamp - request statistics from this timestamp until now. You provide the timestamp as UNIX epoch time. You can get a timestamp for a timeframe by making a REST request to the endpoint with a zoom level.

The following is a sample request to the endpoint with no parameters:

curl -u admin:password http://localhost:8091/pools/default/buckets/bucket_name/stats

Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.

The actual request appears as follows:

GET /pools/default/buckets/<bucket name>/stats
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json X-memcachekv-Store-Client-Specification-Version: 0.1

Upon success, you will see output similar to the following:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{
    "op": {
        "samples": {
            "hit_ratio": [
                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
            ],
            "ep_cache_miss_rate": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                                    0 ],


                .....


            "samplesCount": 60,
            "isPersistent": true,
            "lastTStamp":513777166.0,
            "interval": 1000
        },
        "hot_keys": [
            {
                "name": "48697",
                "ops": 0.0009276437847866419
            },
            {
                "name": "8487",
                "ops": 0.0009276437847866419
            },
            {
                "name": "77262",
                "ops": 0.0009276437847866419
            },
            {
                "name": "58495",
                "ops": 0.0009276437847866419
            },
            {
                "name": "21003",
                "ops": 0.0009276437847866419
            },
            {
                "name": "26850",
                "ops": 0.0009276437847866419
            },
            {
                "name": "73717",
                "ops": 0.0009276437847866419
            },
            {
                "name": "86218",
                "ops": 0.0009276437847866419
            },
            {
                "name": "80344",
                "ops": 0.0009276437847866419
            },
            {
                "name": "83457",
                "ops": 0.0009276437847866419
            }
        ]
    }
}

The following are sample requests at this endpoint with optional parameters. Replace the admin, password, localhost, bucket_name, and 1376963720000 values in the below examples with your actual values.

curl -X GET -u admin:password  -d zoom=minute http://localhost:8091/pools/default/buckets/bucket_name/stats

This will sample statistics from a bucket for the last minute.

curl -X GET -u admin:password  -d zoom=day http://localhost:8091/pools/default/buckets/bucket_name/stats

This will sample statistics from a bucket for the past day.

Using zoom level of a month:

curl -X GET -u admin:password  -d zoom=month http://localhost:8091/pools/default/buckets/bucket_name/stats

This will sample statistics from a bucket for the last month.

Using zoom level of an hour from a specific timestamp:

curl -X GET -u admin:password  -d zoom=hour&haveTStamp=1376963720000 http://localhost:8091/pools/default/buckets/bucket_name/stats

This will sample statistics from a bucket from the timestamp until the server receives the REST request.

Sample output for each of these requests appears in the same format and with the same fields. Depending on the level of bucket activity, there may be more detail for each field or less. For the sake of brevity we have omitted sample output for each category.

{
  "hot_keys": [],
  "op": {
    "interval": 1000,
    "lastTStamp": 1376963580000,
    "isPersistent": true,
    "samplesCount": 1440,
    "samples": {
      "timestamp": [1376955060000, 1376955120000, 1376955180000, 1376955240000, ... ],
      "xdc_ops": [0, 0, 0, 0, ... ],
      "vb_total_queue_age": [0, 0, 0, 0, ... ],
      "vb_replica_queue_size": [0, 0, 0, 0, ... ],
      "vb_replica_queue_fill": [0, 0, 0, 0, ... ],
      "vb_replica_queue_drain": [0, 0, 0, 0, ... ],
      "vb_replica_queue_age": [0, 0, 0, 0, ... ],
      "vb_replica_ops_update": [0, 0, 0, 0, ... ],
      "vb_replica_ops_create": [0, 0, 0, 0, ... ],
      "vb_replica_num_non_resident": [0, 0, 0, 0, ... ],
      "vb_replica_num": [0, 0, 0, 0, ... ],
      "vb_replica_meta_data_memory": [0, 0, 0, 0, ... ],
      "vb_replica_itm_memory": [0, 0, 0, 0, ... ],
      "vb_replica_eject": [0, 0, 0, 0, ... ],
      "vb_replica_curr_items": [0, 0, 0, 0, ... ],
      "vb_pending_queue_size": [0, 0, 0, 0, ... ],
      "vb_pending_queue_fill": [0, 0, 0, 0, ... ],
      "vb_pending_queue_drain": [0, 0, 0, 0, ... ],
      "vb_pending_queue_age": [0, 0, 0, 0, ... ],
      "vb_pending_ops_update": [0, 0, 0, 0, ... ],
      "vb_pending_ops_create": [0, 0, 0, 0, ... ],
      "vb_pending_num_non_resident": [0, 0, 0, 0, ... ],
      "vb_pending_num": [0, 0, 0, 0, ... ],
      "vb_pending_meta_data_memory": [0, 0, 0, 0, ... ],
      "vb_pending_itm_memory": [0, 0, 0, 0, ... ],
      "vb_pending_eject": [0, 0, 0, 0, ... ],
      "vb_pending_curr_items": [0, 0, 0, 0, ... ],
      "vb_active_queue_size": [0, 0, 0, 0, ... ],
      "vb_active_queue_fill": [0, 0, 0, 0, ... ],
      "vb_active_queue_drain": [0, 0, 0, 0, ... ],
      "vb_active_queue_age": [0, 0, 0, 0, ... ],
      "vb_active_ops_update": [0, 0, 0, 0, ... ],
      "vb_active_ops_create": [0, 0, 0, 0, ... ],
      "vb_active_num_non_resident": [0, 0, 0, 0, ... ],
      "vb_active_num": [1024, 1024, 1024, 1024, ... ],
      "vb_active_meta_data_memory": [0, 0, 0, 0, ... ],
      "vb_active_itm_memory": [0, 0, 0, 0, ... ],
      "vb_active_eject": [0, 0, 0, 0, ... ],
      "ep_ops_create": [0, 0, 0, 0, ... ],
      "ep_oom_errors": [0, 0, 0, 0, ... ],
      "ep_num_value_ejects": [0, 0, 0, 0, ... ],
      "ep_num_ops_set_ret_meta": [0, 0, 0, 0, ... ],
      "ep_num_ops_set_meta": [0, 0, 0, 0, ... ],
      "ep_num_ops_get_meta": [0, 0, 0, 0, ... ],
      "ep_num_ops_del_ret_meta": [0, 0, 0, 0, ... ],
      "ep_num_ops_del_meta": [0, 0, 0, 0, ... ],
      "ep_num_non_resident": [0, 0, 0, 0, ... ],
      "ep_meta_data_memory": [0, 0, 0, 0, ... ],
      "ep_mem_low_wat": [402653184, 402653184, 402653184, 402653184, ... ],
      "ep_mem_high_wat": [456340275, 456340275, 456340275, 456340275, ... ],
      "ep_max_data_size": [536870912, 536870912, 536870912, 536870912, ... ],
      "ep_kv_size": [0, 0, 0, 0, ... ],
      "ep_item_commit_failed": [0, 0, 0, 0, ... ],
      "ep_flusher_todo": [0, 0, 0, 0, ... ],
      "ep_diskqueue_items": [0, 0, 0, 0, ... ],
      "ep_diskqueue_fill": [0, 0, 0, 0, ... ],
      "ep_diskqueue_drain": [0, 0, 0, 0, ... ],
      "ep_bg_fetched": [0, 0, 0, 0, ... ],
      "disk_write_queue": [0, 0, 0, 0, ... ],
      "disk_update_total": [0, 0, 0, 0, ... ],
      "disk_update_count": [0, 0, 0, 0, ... ],
      "disk_commit_total": [0, 0, 0, 0, ... ],
      "disk_commit_count": [0, 0, 0, 0, ... ],
      "delete_misses": [0, 0, 0, 0, ... ],
      "delete_hits": [0, 0, 0, 0, ... ],
      "decr_misses": [0, 0, 0, 0, ... ],
      "decr_hits": [0, 0, 0, 0, ... ],
      "curr_items_tot": [0, 0, 0, 0, ... ],
      "curr_items": [0, 0, 0, 0, ... ],
      "curr_connections": [9, 9, 9, 9, ... ],
      "avg_bg_wait_time": [0, 0, 0, 0, ... ],
      "avg_disk_commit_time": [0, 0, 0, 0, ... ],
      "avg_disk_update_time": [0, 0, 0, 0, ... ],
      "vb_pending_resident_items_ratio": [0, 0, 0, 0, ... ],
      "vb_replica_resident_items_ratio": [0, 0, 0, 0, ... ],
      "vb_active_resident_items_ratio": [0, 0, 0, 0, ... ],
      "vb_avg_total_queue_age": [0, 0, 0, 0, ... ],
      "vb_avg_pending_queue_age": [0, 0, 0, 0, ... ],
      "couch_total_disk_size": [8442535, 8449358, 8449392, 8449392, ... ],
      "couch_docs_fragmentation": [0, 0, 0, 0, ... ],
      "couch_views_fragmentation": [0, 0, 0, 0, ... ],
      "hit_ratio": [0, 0, 0, 0, ... ],
      "ep_cache_miss_rate": [0, 0, 0, 0, ... ],
      "ep_resident_items_rate": [100, 100, 100, 100, ... ],
      "vb_avg_active_queue_age": [0, 0, 0, 0, ... ],
      "vb_avg_replica_queue_age": [0, 0, 0, 0, ... ],
      "bg_wait_count": [0, 0, 0, 0, ... ],
      "bg_wait_total": [0, 0, 0, 0, ... ],
      "bytes_read": [103.5379762658911, 103.53627151841438, 103.53627262555834, 103.53739884434893, ... ],
      "bytes_written": [20793.105529503482, 20800.99759272974, 20802.109356966503, 20803.59949917707, ... ],
      "cas_badval": [0, 0, 0, 0, ... ],
      "cas_hits": [0, 0, 0, 0, ... ],
      "cas_misses": [0, 0, 0, 0, ... ],
      "cmd_get": [0, 0, 0, 0, ... ],
      "cmd_set": [0, 0, 0, 0, ... ],
      "couch_docs_actual_disk_size": [8442535, 8449358, 8449392, 8449392, ... ],
      "couch_docs_data_size": [8435712, 8435712, 8435712, 8435712, ... ],
      "couch_docs_disk_size": [8435712, 8435712, 8435712, 8435712, ... ],
      "couch_views_actual_disk_size": [0, 0, 0, 0, ... ],
      "couch_views_data_size": [0, 0, 0, 0, ... ],
      "couch_views_disk_size": [0, 0, 0, 0, ... ],
      "couch_views_ops": [0, 0, 0, 0, ... ],
      "ep_ops_update": [0, 0, 0, 0, ... ],
      "ep_overhead": [27347928, 27347928, 27347928, 27347928, ... ],
      "ep_queue_size": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_count": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_qlen": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_queue_backfillremaining": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_queue_backoff": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_queue_drain": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_queue_fill": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_queue_itemondisk": [0, 0, 0, 0, ... ],
      "ep_tap_rebalance_total_backlog_size": [0, 0, 0, 0, ... ],
      "ep_tap_replica_count": [0, 0, 0, 0, ... ],
      "ep_tap_replica_qlen": [0, 0, 0, 0, ... ],
      "ep_tap_replica_queue_backfillremaining": [0, 0, 0, 0, ... ],
      "ep_tap_replica_queue_backoff": [0, 0, 0, 0, ... ],
      "ep_tap_replica_queue_drain": [0, 0, 0, 0, ... ],
      "ep_tap_replica_queue_fill": [0, 0, 0, 0, ... ],
      "ep_tap_replica_queue_itemondisk": [0, 0, 0, 0, ... ],
      "ep_tap_replica_total_backlog_size": [0, 0, 0, 0, ... ],
      "ep_tap_total_count": [0, 0, 0, 0, ... ],
      "ep_tap_total_qlen": [0, 0, 0, 0, ... ],
      "ep_tap_total_queue_backfillremaining": [0, 0, 0, 0, ... ],
      "ep_tap_total_queue_backoff": [0, 0, 0, 0, ... ],
      "ep_tap_total_queue_drain": [0, 0, 0, 0, ... ],
      "ep_tap_total_queue_fill": [0, 0, 0, 0, ... ],
      "ep_tap_total_queue_itemondisk": [0, 0, 0, 0, ... ],
      "ep_tap_total_total_backlog_size": [0, 0, 0, 0, ... ],
      "ep_tap_user_count": [0, 0, 0, 0, ... ],
      "ep_tap_user_qlen": [0, 0, 0, 0, ... ],
      "ep_tap_user_queue_backfillremaining": [0, 0, 0, 0, ... ],
      "ep_tap_user_queue_backoff": [0, 0, 0, 0, ... ],
      "ep_tap_user_queue_drain": [0, 0, 0, 0, ... ],
      "ep_tap_user_queue_fill": [0, 0, 0, 0, ... ],
      "ep_tap_user_queue_itemondisk": [0, 0, 0, 0, ... ],
      "ep_tap_user_total_backlog_size": [0, 0, 0, 0, ... ],
      "ep_tmp_oom_errors": [0, 0, 0, 0, ... ],
      "ep_vb_total": [1024, 1024, 1024, 1024, ... ],
      "evictions": [0, 0, 0, 0, ... ],
      "get_hits": [0, 0, 0, 0, ... ],
      "get_misses": [0, 0, 0, 0, ... ],
      "incr_hits": [0, 0, 0, 0, ... ],
      "incr_misses": [0, 0, 0, 0, ... ],
      "mem_used": [27347928, 27347928, 27347928, 27347928, ... ],
      "misses": [0, 0, 0, 0, ... ],
      "ops": [0, 0, 0, 0, ... ],
      "replication_active_vbreps": [0, 0, 0, 0, ... ],
      "replication_bandwidth_usage": [0, 0, 0, 0, ... ],
      "replication_changes_left": [0, 0, 0, 0, ... ],
      "replication_commit_time": [0, 0, 0, 0, ... ],
      "replication_data_replicated": [0, 0, 0, 0, ... ],
      "replication_docs_checked": [0, 0, 0, 0, ... ],
      "replication_docs_latency_aggr": [0, 0, 0, 0, ... ],
      "replication_docs_latency_wt": [0, 0, 0, 0, ... ],
      "replication_docs_rep_queue": [0, 0, 0, 0, ... ],
      "replication_docs_written": [0, 0, 0, 0, ... ],
      "replication_meta_latency_aggr": [0, 0, 0, 0, ... ],
      "replication_meta_latency_wt": [0, 0, 0, 0, ... ],
      "replication_num_checkpoints": [0, 0, 0, 0, ... ],
      "replication_num_failedckpts": [0, 0, 0, 0, ... ],
      "replication_rate_replication": [0, 0, 0, 0, ... ],
      "replication_size_rep_queue": [0, 0, 0, 0, ... ],
      "replication_waiting_vbreps": [0, 0, 0, 0, ... ],
      "replication_work_time": [0, 0, 0, 0, ... ]
    }
  }
}

Using the bucket streaming URI

The individual bucket request is exactly the same as what would be obtained from the item in the array for the entire buckets list described previously. The streamingUri is exactly the same except it streams HTTP chunks using chunked encoding. A response of “\n\n\n\n” delimits chunks. This will likely be converted to a “zero chunk” in a future release of this API, and thus the behavior of the streamingUri should be considered evolving.

GET /pools/default/buckets/default
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{
  "name": "default",
  "bucketType": "couchbase",
  "authType": "sasl",
  "saslPassword": "",
  "proxyPort": 0,
  "uri": "/pools/default/buckets/default",
  "streamingUri": "/pools/default/bucketsStreaming/default",
  "flushCacheUri": "/pools/default/buckets/default/controller/doFlush",
  "nodes": [
    {
      "uptime": "308",
      "memoryTotal": 3940818944.0,
      "memoryFree": 1608724480,
      "mcdMemoryReserved": 3006,
      "mcdMemoryAllocated": 3006,
      "replication": 1.0,
      "clusterMembership": "active",
      "status": "healthy",
      "hostname": "172.25.0.2:8091",
      "clusterCompatibility": 1,
      "version": "1.6.4r_107_g49a149d",
      "os": "i486-pc-linux-gnu",
      "ports": {
        "proxy": 11211,
        "direct": 11210
      }
    },
    {
      "uptime": "308",
      "memoryTotal": 3940818944.0,
      "memoryFree": 1608724480,
      "mcdMemoryReserved": 3006,
      "mcdMemoryAllocated": 3006,
      "replication": 1.0,
      "clusterMembership": "active",
      "status": "healthy",
      "hostname": "172.25.0.3:8091",
      "clusterCompatibility": 1,
      "version": "1.6.4r_107_g49a149d",
      "os": "i486-pc-linux-gnu",
      "ports": {
        "proxy": 11211,
        "direct": 11210
      }
    },
    {
      "uptime": "308",
      "memoryTotal": 3940818944.0,
      "memoryFree": 1608597504,
      "mcdMemoryReserved": 3006,
      "mcdMemoryAllocated": 3006,
      "replication": 1.0,
      "clusterMembership": "active",
      "status": "healthy",
      "hostname": "172.25.0.4:8091",
      "clusterCompatibility": 1,
      "version": "1.6.4r_107_g49a149d",
      "os": "i486-pc-linux-gnu",
      "ports": {
        "proxy": 11211,
        "direct": 11210
      }
    }
  ],
  "stats": {
    "uri": "/pools/default/buckets/default/stats"
  },
  "nodeLocator": "vbucket",
  "vBucketServerMap": {
    "hashAlgorithm": "CRC",
    "numReplicas": 1,
    "serverList": [
      "172.25.0.2:11210",
      "172.25.0.3:11210",
      "172.25.0.4:11210"
    ],
    "vBucketMap": [
      [1,0],
      [2,0],
      [1,2],
      [2,1],
      [1,2],
      [0,2],
      [0,1],
      [0,1]
    ]
  },
  "replicaNumber": 1,
  "quota": {
    "ram": 1887436800,
    "rawRAM":145600
  },
  "basicStats": {
    "quotaPercentUsed": 14.706055058373344,
    "opsPerSec": 0,
    "diskFetches": 0,
    "itemCount": 65125,
    "diskUsed": 139132928,
    "memUsed": 277567495
  }
}

Creating and editing buckets

You can create a new bucket with a POST command sent to the URI for buckets in a cluster. This can be used to create either a Couchbase or a Memcached type bucket. The bucket name cannot have a leading underscore.

To create a new Couchbase bucket, or edit the existing parameters for an existing bucket, you can send a POST to the REST API endpoint. You can also use this same endpoint to get a list of buckets that exist for a cluster.

Note

Be aware that when you edit bucket properties, if you do not specify an existing bucket property Couchbase Server may reset this the property to be the default. So even if you do not intend to change a certain property when you edit a bucket, you should specify the existing value to avoid this behavior.

The REST API returns a successful response when preliminary files for a data bucket are created on one node. Because you may be using a multi-node cluster, bucket creation may not yet be complete for all nodes when a response is sent. Therefore it is possible that the bucket is not available for operations immediately after this REST call successful returns.

To ensure a bucket is available, the recommended approach is try to read a key from the bucket. If you receive a ‘key not found’ error, or the document for the key, the bucket exists and is available to all nodes in a cluster. You can do this via a Couchbase SDK with any node in the cluster. See the Couchbase Developer Guide for more information.

Method - POST /pools/default/buckets
Request Data - List of payload parameters for the new bucket
Response Data - JSON of the bucket confirmation or error condition
Authentication Required - yes

Payload Arguments Description
authType Required parameter. Type of authorization to be enabled for the new bucket as a string. Defaults to blank password if not specified. “sasl” enables authentication. “none” disables authentication.
bucketType Required parameter. Type of bucket to be created. String value. “memcached” configures as Memcached bucket. “couchbase” configures as Couchbase bucket
flushEnabled Optional parameter. Enables the ‘flush all’ functionality on the specified bucket. Boolean. 1 enables flush all support, 0 disables flush all support. Defaults to 0.
name Required parameter. Name for new bucket.
parallelDBAndViewCompaction Optional parameter. String value. Indicates whether database and view files on disk can be compacted simultaneously. Defaults to “false.”
proxyPort Required parameter. Numeric. Proxy port on which the bucket communicates. Must be a valid network port which is not already in use. You must provide a valid port number if the authorization type is not SASL.
ramQuotaMB Required parameter. RAM Quota for new bucket in MB. Numeric. The minimum you can specify is 100, and the maximum can only be as great as the memory quota established for the node. If other buckets are associated with a node, RAM Quota can only be as large as the amount memory remaining for the node, accounting for the other bucket memory quota.
replicaIndex Optional parameter. Boolean. 1 enable replica indexes for replica bucket data while 0 disables. Default of 1.
replicaNumber Optional parameter. Numeric. Number of replicas to be configured for this bucket. Required parameter when creating a Couchbase bucket. Default 1, minimum 0, maximum 3.
saslPassword Optional Parameter. String. Password for SASL authentication. Required if SASL authentication has been enabled.
threadsNumber Optional Parameter. Integer from 2 to 8. Change the number of concurrent readers and writers for the data bucket. For detailed information about this feature, see Using Multi- Readers and Writers.
Return Codes
202 Accepted
204 Bad Request JSON with errors in the form of {“errors”: {…. }} name: Bucket with given name already exists ramQuotaMB: RAM Quota is too large or too small replicaNumber: Must be specified and must be a non-negative integer proxyPort: port is invalid, port is already in use
404 Object Not Found

When you create a bucket you must provide the authType parameter:

  • If you set authType to none, then you must specify a proxyPort number.

  • If you set authType to sasl, then you may optionally provide a saslPassword parameter.

The ramQuotaMB parameter specifies how much memory, in megabytes, you want to allocate to each node for the bucket. The minimum supported value is 100MB.

  • If the items stored in a memcached bucket take space beyond the ramQuotaMB, Couchbase Sever typically will evict items on least-requested-item basis. Couchbase Server may evict other infrequently used items depending on object size, or whether or not an item is being referenced.

  • In the case of Couchbase buckets, the system may return temporary failures if the ramQuotaMB is reached. The system will try to keep 25% of the available ramQuotaMB free for new items by ejecting old items from occupying memory. In the event these items are later requested, they will be retrieved from disk.

For example:

curl -X POST -u admin:password -d name=newbucket -d ramQuotaMB=200 -d authType=none \
-d replicaNumber=2 -d proxyPort=11215 http://localhost:8091/pools/default/buckets

Replace the admin, password, localhost, newbucket, 200, 2, and 11215 values in the above example with your actual values.

The parameters for configuring the bucket are provided as payload data, with each parameter and value provided as a key/value pair, separated by an ampersand.

The HTTP request should include the parameters setting in the payload of the POST request:

POST /pools/default/buckets
HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
name=newbucket&ramQuotaMB=20&authType=none&replicaNumber=2&proxyPort=11215

If the bucket creation was successful, HTTP response 202 (Accepted) will be returned with empty content.

202 Accepted

If the bucket could not be created, because the parameter was missing or incorrect, HTTP response 400 will be returned, with a JSON payload containing the error reason.

Getting bucket configuration

To obtain the information about an existing bucket, use the main REST API bucket endpoint with the bucket name. For example:

GET /pools/default/buckets/bucketname
HTTP/1.1 200 OK
Content-Type: application/com.couchbase.store+json
Content-Length: nnn
{
    "name" : "Another bucket",
    "bucketRules" :
    {
        "cacheRange" :
        {
            "min" : 1,
            "max" : 599
        },
        "replicationFactor" : 2
    }
    "nodes" : [
        {
            "hostname" : "10.0.1.20",
            "uri" : "/addresses/10.0.1.20",
            "status" : "healthy",
            "ports" :
            {
                "routing" : 11211,
                "kvcache" :1
            }
        },
        {
            "hostname" : "10.0.1.21",
            "uri" : "/addresses/10.0.1.21",
            "status" : "healthy",
            "ports" :
            {
                "routing" : 11211,
                "kvcache" :1
            }
        }
    ]
}

Clients MUST use the nodes list from the bucket, not the pool to indicate which are the appropriate nodes to connect to.

Modifying bucket parameters

You can modify existing bucket parameters by posting the updated parameters used to create the bucket to the bucket’s URI. Do not omit a parameter in your request since this is equivalent to not setting it in many cases. We recommend you do a request to get current bucket settings, make modifications as needed and then make your POST request to the bucket URI.

For example, to edit the bucket customer :

curl -v -X POST -u admin:password -d name=customer \
-d flushEnabled=0 -d replicaNumber=1 -d authType=none \
-d ramQuotaMB=200 -d proxyPort=11212 \
 http://localhost:8091/pools/default/buckets/customer

Replace the admin, password, localhost, customer, 0, 1, 200, 11212, and customer values in the above example with your actual values.

Available parameters are identical to those available when creating a bucket. See bucket parameters.

If the request is successful, HTTP response 200 will be returned with an empty data content.

Warning

The bucket name cannot be changed via the REST API.

Increasing bucket memory quota

You can increase and decrease a bucket’s ramQuotaMB from its current level. However, while increasing will do no harm, decreasing should be done with proper sizing. Decreasing the bucket’s ramQuotaMB lowers the watermark, and some items may be unexpectedly ejected if the ramQuotaMB is set too low.

Note

There are some known issues with changing the ramQuotaMB for memcached bucket types.

Example of a request:

curl -X POST -u admin:password -d ramQuotaMB=25 -d authType=none \
-d proxyPort=11215 http://localhost:8091/pools/default/buckets/newbucket

Replace the admin, password, localhost, 25, 11215, and new_bucket values in the above example with your actual values.

The response will be 202, indicating the quota will be changed asynchronously throughout the servers in the cluster. An example:

HTTP/1.1 202 OK
Server: Couchbase Server 1.6.0
Pragma: no-cache
Date: Wed, 29 Sep 2010 20:01:37 GMT
Content-Length: 0
Cache-Control: no-cache no-store max-age=0

Changing bucket authentication

Changing a bucket from port based authentication to SASL authentication can be achieved by changing the active bucket configuration. You must specify the existing configuration parameters and the changed authentication parameters in the request:

curl -X POST -u admin:password -d ramQuotaMB=130 -d authType=sasl \
-d saslPassword=letmein \
http://localhost:8091/pools/default/buckets/acache

Replace the admin, password, localhost, 130, letmein, and acache values in the above example with your actual values.

Deleting buckets

Method DELETE /pools/default/buckets/bucket_name
Request Data None
Response Data None
Authentication Required yes
Return Codes
200 OK Bucket Deleted on all nodes
401 Unauthorized
404 Object Not Found
500 Bucket could not be deleted on all nodes
503 Buckets cannot be deleted during a rebalance

Warning

This operation is data destructive.The service makes no attempt to double check with the user. It simply moves forward. Clients applications using this are advised to double check with the end user before sending such a request.

To delete a bucket, you supply the URL of the Couchbase bucket using the DELETE operation. For example:

DELETE /pools/default/buckets/default
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx

Bucket deletion is a synchronous operation but because the cluster may include a number of nodes, they may not all be able to delete the bucket. If all the nodes delete the bucket within the standard timeout of 30 seconds, 200 will be returned. If the bucket cannot be deleted on all nodes within the 30 second timeout, a 500 is returned.

Further requests to delete the bucket will return a 404 error. Creating a new bucket with the same name may return an error that the bucket is still being deleted.

Flushing buckets

Warning

This operation is data destructive. The service makes no attempt to confirm or double check the request. Client applications using this are advised to double check with the end user before sending such a request. You can control and limit the ability to flush individual buckets by setting the flushEnabled parameter on a bucket in Couchbase Web Console or via cbepctl flush_param.

For information about changing this setting in the Web Console, see Viewing Data Buckets.

The doFlush operation empties the contents of the specified bucket, deleting all stored data. The operation will only succeed if flush is enabled on configured bucket. The format of the request is the URL of the REST endpoint using the POST HTTP operation:

http://localhost:8091/pools/default/buckets/default/controller/doFlush

For example, using curl :

curl -X POST 'http://admin:password@localhost:8091/pools/default/buckets/default/controller/doFlush'

Replace the admin, password, and localhost values in the above example with your actual values.

The equivalent HTTP protocol request:

POST /pools/default/buckets/default/controller/doFlush
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx

Parameters and payload data are ignored, but the request must including the authorization header if the system has been secured.

If flushing is disable for the specified bucket, a 400 response will be returned with the bucket status:

{"_":"Flush is disabled for the bucket"}

If the flush is successful, the HTTP response code is 200 :

HTTP/1.1 200 OK

Warning

The flush request may lead to significant disk activity as the data in the bucket is deleted from the database. The high disk utilization may affect the performance of your server until the data has been successfully deleted.

Note

The flush request is not transmitted over XDCR replication configurations; the remote bucket will not be flushed.

Couchbase Server returns a HTTP 404 response if the URI is invalid or if it does not correspond to an active bucket in the system.

404 Not Found

You can configure whether flush is enabled for a bucket by configuring the individual bucket properties, either the REST API (see Modifying Bucket Parameters ), or through the Admin Console (see Creating and Editing Data Buckets ).

Views REST API

You can index and query JSON documents using views. Views are functions written in JavaScript that can serve several purposes in your application. You can use them to: find all the documents in your database, create a copy of data in a document and present it in a specific order, create an index to efficiently find documents by a particular value or by a particular structure in the document, represent relationships between documents, and perform calculations on data contained in documents.

You store view functions in a design document as JSON and can use the REST API to manage your design documents.

Querying views with REST

Querying can be performed through the REST API endpoint. The REST API supports and operates using the core HTTP protocol, and this is the same system used by the client libraries to obtain the view data.

Use the REST API to query a view by accessing any node within the Couchbase Server cluster on port 8092. For example:

GET http://localhost:8092/bucketname/_design/designdocname/_view/viewname

Where:

  • bucketname is the name of the bucket.

  • designdocname is the name of the design document that contains the view.

    For views defined within the development context (see Development and Production Views ), the designdocname is prefixed with dev_. For example, the design document beer is accessible as a development view using dev_beer.

    Production views are accessible using their name only.

  • viewname is the name of the corresponding view within the design document.

When accessing a view stored within an SASL password-protected bucket, you must include the bucket name and bucket password within the URL of the request:

GET http://bucketname:password@localhost:8092/bucketname/_design/designdocname/_view/viewname

Additional arguments to the URL request can be used to select information from the view, and provide limit, sorting and other options. For example, to output only ten items:

GET http://localhost:8092/bucketname/_design/designdocname/_view/viewname?limit=10

The formatting of the URL follows the HTTP specification. The first argument should be separated from the base URL using a question mark ( ? ). Additional arguments should be separated using an ampersand ( & ). Special characters should be quoted or escaped according to the HTTP standard rules.

The additional supported arguments are detailed in the table below.

Get View Name Description
Method GET /bucket/_design/design-doc/_view/view-name
Request Data None
Response Data JSON of the rows returned by the view
Authentication Required no
Query Arguments
descending Return the documents in descending by key order
Parameters : boolean; optional
endkey Stop returning records when the specified key is reached. Key must be specified as a JSON value.
Parameters : string; optional
endkey_docid Stop returning records when the specified document ID is reached
Parameters : string; optional
full_set Use the full cluster data set (development views only).
Parameters : boolean; optional
group Group the results using the reduce function to a group or single row
Parameters : boolean; optional
group_level Specify the group level to be used
Parameters : numeric; optional
inclusive_end Specifies whether the specified end key should be included in the result
Parameters : boolean; optional
key Return only documents that match the specified key. Key must be specified as a JSON value.
Parameters : string; optional
keys Return only documents that match each of keys specified within the given array. Key must be specified as a JSON value. Sorting is not applied when using this option.
Parameters : array; optional
limit Limit the number of the returned documents to the specified number
Parameters : numeric; optional
on_error Sets the response in the event of an error
Parameters : string; optional
Supported Values
continue : Continue to generate view information in the event of an error, including the error information in the view response stream.
stop : Stop immediately when an error condition occurs. No further view information will be returned.
reduce Use the reduction function
Parameters : boolean; optional
skip Skip this number of records before starting to return the results
Parameters : numeric; optional
stale Allow the results from a stale view to be used
Parameters : string; optional
Supported Values :
false : Force a view update before returning data
ok : Allow stale views
update_after : Allow stale view, update view after it has been accessed
startkey Return records with a value equal to or greater than the specified key. Key must be specified as a JSON value.
Parameters : string; optional
startkey_docid Return records starting with the specified document ID
Parameters : string; optional

The output from a view will be a JSON structure containing information about the number of rows in the view, and the individual view information.

An example of the View result is shown below:

{
  "total_rows": 576,
  "rows" : [
      {"value" : 13000, "id" : "James", "key" : ["James", "Paris"] },
      {"value" : 20000, "id" : "James", "key" : ["James", "Tokyo"] },
      {"value" : 5000,  "id" : "James", "key" : ["James", "Paris"] },
…
    ]
}

The JSON returned consists of two fields:

  • total_rows

    A count of the number of rows of information within the stored View. This shows the number of rows in the full View index, not the number of rows in the returned data set.

  • rows

    An array, with each element of the array containing the returned view data, consisting of the value, document ID that generated the row, and the key.

In the event of an error, the HTTP response will be an error type (not 200), and a JSON structure will be returned containing two fields, the basic error and a more detailed reason field. For example:

{
  "error":"bad_request",
  "reason":"invalid UTF-8 JSON: {{error,{1,\"lexical error: invalid char in json text.\\n\"}},\n                     \"Paris\"}"
}

Note

If you supply incorrect parameters to the query, an error message is returned by the server. Within the Client Libraries the precise behavior may differ between individual language implementations, but in all cases, an invalid query should trigger an appropriate error or exception.

Limiting simultaneous node requests

You can use the /internalSettings endpoint to limit the number of simultaneous requests each node can accept. In earlier releases, too many simultaneous views requests resulted in a node being overwhelmed. For general information about this endpoint, see Managing Internal Cluster Settings.

 When Couchbase Server rejects an incoming connection because one of these limits is exceeded, it responds with an HTTP status code of 503. The HTTP Retry-After header will be set appropriately. If the request is made to a REST port, the response body will provide the reason why the request was rejected. If the request is made on a CAPI port, such as a views request, the server will respond with a JSON object with a “error” and “reason” fields.

For example, to change this limit for the port used for views:

curl -X POST -u admin:password http://localhost:8091/internalSettings -d 'capiRequestLimit=50'

Replace the admin, password, localhost, and 50 values in the above example with your actual values.

Will limit the number of simultaneous views requests and internal XDCR requests which can be made on a port. The following are all the port-related request parameters you can set:

  • restRequestLimit : Maximum number of simultaneous connections each node should accept on a REST port. Diagnostic-related requests and  /internalSettings requests are not counted in this limit.

  • capiRequestLimit : Maximum number of simultaneous connections each node should accept on CAPI port. This port is used for XDCR and views connections.

  • dropRequestMemoryThresholdMiB : In MB. The amount of memory used by Erlang VM that should not be exceeded. If the amount is exceeded the server will start dropping incoming connections.

By default these settings do not have any limit set. We recommend you leave this settings at the default setting unless you experience issues with too many requests impacting a node. If you set these thresholds too low, too many requests will be rejected by the server, including requests from Couchbase Web Console.

Design documents REST API

Design documents are used to store one or more view definitions. Views can be defined within a design document and uploaded to the server through the REST API.

Storing design documents

To create a new design document with one or more views, you can upload the corresponding design document using the REST API with the definition in place. The format of this command is as shown in the table below:

Put Design Document Description
Method PUT /bucket/_design/design-doc
Request Data Design document definition (JSON)
Response Data Success and stored design document ID
Authentication Required optional
Return Codes
201 Document created successfully.
401 The item requested was not available using the supplied authorization, or authorization was not supplied.

Note

When creating a design document through the REST API, we recommend that you create a development ( dev ) view. We recommend that you create a dev design document and views first, and then check the output of the configured views in your design document. To create a dev view you must explicitly use the dev_ prefix for the design document name.

For example, using curl, you can create a design document, byfield, by creating a text file (with the name byfield.ddoc ) with the design document content using the following command:

curl -X PUT -H 'Content-Type: application/json' \
   http://user:password@localhost:8092/sales/_design/dev_byfield \
   -d @byfield.ddoc

In the above example:

  • -X PUT

    Indicates that an HTTP PUT operation is requested.

  • -H ‘Content-Type: application/json’

    Specifies the HTTP header information. Couchbase Server requires the information to be sent and identified as the application/json datatype. Information not supplied with the content-type set in this manner will be rejected.

  • http://user:password@localhost:8092/sales/_design/dev_byfield

    The URL, including authentication information, of the bucket where you want the design document uploaded. The user and password should either be the Administration privileges, or for SASL protected buckets, the bucket name and bucket password. If the bucket does not have a password, then the authentication information is not required.

Note

The view being accessed in this case is a development view. To create a development view, you must use the dev_ prefix to the view name.

As a PUT command, the URL is also significant, in that the location designates the name of the design document. In the example, the URL includes the name of the bucket ( sales ) and the name of the design document that will be created dev_byfield.

  • -d @byfield.ddoc

    Specifies that the data payload should be loaded from the file byfield.ddoc.

If successful, the HTTP response code will be 201 (created). The returned JSON will contain the field ok and the ID of the design document created:

{
    "ok":true,
    "id":"_design/dev_byfield"
}

The design document will be validated before it is created or updated in the system. The validation checks for valid JavaScript and for the use of valid built-in reduce functions. Any validation failure is reported as an error.

In the event of an error, the returned JSON will include the field error with a short description, and the field reason with a longer description of the problem.

The format of the design document should include all the views defined in the design document, incorporating both the map and reduce functions for each named view. For example:

{"views":{"byloc":{"map":"function (doc, meta) {\n  if (meta.type == \"json\") {\n    emit(doc.city, doc.sales);\n  } else {\n    emit([\"blob\"]);\n  }\n}"}}}

Formatted, the design document looks like this:

{
   "views" : {
      "byloc" : {
         "map" : "function (doc, meta) {\n  if (meta.type == \"json\") {\n    emit(doc.city, doc.sales);\n  } else {\n    emit([\"blob\"]);\n  }\n}"
      }
   }
}

The top-level views field lists one or more view definitions (the byloc view in this example), and for each view, a corresponding map() function.

Retrieving design documents

To obtain an existing design document from a given bucket, you need to access the design document from the corresponding bucket using a GET request, as detailed in the table below.

Get Design Document Description
Method GET /bucket/_design/design-doc
Request Data Design document definition (JSON)
Response Data Success and stored design document ID
Authentication Required optional
Return Codes
200 Request completed successfully.
401 The item requested was not available using the supplied authorization, or authorization was not supplied.
404 The requested content could not be found. The returned content will include further information, as a JSON object, if available.

To get back all the design documents with views defined on a bucket, the use following URI path with the GET request. In addition to get specific design documents back, the name of the design document can be specified to retrieve it.

"ddocs": {
        "uri": "/pools/default/buckets/default/ddocs" // To obtain design docs for this bucket
    }

For example, to get the existing design document from the bucket sales for the design document byfield :

curl -X GET \
    -H 'Content-Type: application/json' \
    http://user:password@192.168.0.77:8092/sales/_design/dev_byfield

Through curl this will download the design document to the file dev_byfield filename.

If the bucket does not have a password, you can omit the authentication information. If the view does not exist you will get an error:

{
   "error":"not_found",
   "reason":"missing"
}

The HTTP response header will include a JSON document containing the metadata about the design document being accessed. The information is returned within the X-Couchbase-Meta header of the returned data. You can obtain this information by using the -v option to the curl.

For example:

curl -v -X GET \
   -H 'Content-Type: application/json' \
   http://user:password@192.168.0.77:8092/sales/_design/
* About to connect() to 192.168.0.77 port 8092 (#0)
*   Trying 192.168.0.77...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* connected
* Connected to 192.168.0.77 (192.168.0.77) port 8092 (#0)
* Server auth using Basic with user 'Administrator'
> GET /sales/_design/something HTTP/1.1
> Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: 192.168.0.77:8092
> Accept: */*
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< X-Couchbase-Meta: {"id":"_design/dev_sample","rev":"5-2785ea87","type":"json"}
< Server: MochiWeb/1.0 (Any of you quaids got a smint?)
< Date: Mon, 13 Aug 2012 10:45:46 GMT
< Content-Type: application/json
< Content-Length: 159
< Cache-Control: must-revalidate
<
{ [data not shown]
100   159  100   159    0     0  41930      0 --:--:-- --:--:-- --:--:-- 53000
* Connection #0 to host 192.168.0.77 left intact
* Closing connection #0

The metadata matches the corresponding metadata for a data document.

Deleting design documents

To delete a design document, you use the DELETE HTTP request with the URL of the corresponding design document. The summary information for this request is shown in the table below:

Delete Design Document Description
Method DELETE /bucket/_design/design-doc
Request Data Design document definition (JSON)
Response Data Success and confirmed design document ID
Authentication Required optional
Return Codes
200 Request completed successfully.
401 The item requested was not available using the supplied authorization, or authorization was not supplied.
404 The requested content could not be found. The returned content will include further information, as a JSON object, if available.

Deleting a design document immediately invalidates the design document and all views and indexes associated with it. The indexes and stored data on disk are removed in the background.

For example, to delete the previously created design document using curl :

curl -v -X DELETE -H 'Content-Type: application/json' \
    http://Administrator:Password@192.168.0.77:8092/default/_design/dev_byfield

When the design document has been successfully removed, the JSON returned indicates successful completion, and confirmation of the design document removed:

{"ok":true,"id":"_design/dev_byfield"}

Error conditions will be returned if the authorization is incorrect, or the specified design document cannot be found.

XDCR REST API

Cross Datacenter Replication (XDCR) enables you to automatically replicate data between clusters and between data buckets. There are several endpoints for the Couchbase REST API that you can use specifically for XDCR. For more information about using and configuring XDCR, see Cross Datacenter Replication (XDCR).

When you use XDCR, you specify source and destination clusters. A source cluster is the cluster from which you want to copy data; a destination cluster is the cluster where you want the replica data to be stored. When you configure replication, you specify your selections for an individual cluster using Couchbase Admin Console. XDCR will replicate data between specific buckets and specific clusters and you can configure replication be either uni-directional or bi-directional. Uni-directional replication means that XDCR replicates from a source to a destination; in contrast, bi-directional replication means that XDCR replicates from a source to a destination and also replicates from the destination to the source. For more information about using Couchbase Web Console to configure XDCR, see Cross Datacenter Replication (XDCR).

Getting a destination cluster reference

When you use XDCR, you establish source and destination cluster. A source cluster is the cluster from which you want to copy data; a destination cluster is the cluster where you want the replica data to be stored. To get information about a destination cluster:

curl -u admin:password 
    http://localhost:8091/pools/default/remoteClusters

Replace the admin, password, and localhost values in the above example with your actual values.

You provide credentials for the cluster and also the hostname and port for the remote cluster. This will generate a request similar to the following sample:

GET /pools/default/remoteClusters HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*

If successful, Couchbase Server responds with a JSON response similar to the following:

[{
"name":"remote1",
"uri":"/pools/default/remoteClusters/remote1",
"validateURI":"/pools/default/remoteClusters/remote1?just_validate=1",
"hostname":"10.4.2.6:8091",
"username":"Administrator",
"uuid":"9eee38236f3bf28406920213d93981a3",
"deleted":false
}]

The following describes the response elements:

  • (String) name: Name of the destination cluster referenced for XDCR.

  • (String) uri: URI for destination cluster information.

  • (String) validateURI: URI to validate details of cluster reference.

  • (String) hostname: Hostname/IP (and :port) of the remote cluster.

  • (String) uuid: UUID of the remote cluster reference.

  • (String) username: Username for the destination cluster administrator.

  • (Boolean) deleted: Indicates whether the reference to the destination cluster has been deleted or not.

For more information about XDCR and using XDCR via the Couchbase Web Console, see Cross Datacenter Replication (XDCR).

Creating a destination cluster reference

When you use XDCR, you establish source and destination cluster. A source cluster is the cluster from which you want to copy data; a destination cluster is the cluster where you want the replica data to be stored. To create a reference to a destination cluster:

curl -v -u admin:password1 http://10.4.2.4:8091/pools/default/remoteClusters \
-d uuid=9eee38236f3bf28406920213d93981a3  \
-d name=remote1
-d hostname=10.4.2.6:8091
-d username=admin -d password=password2

Replace the admin, password1, password2, 10.4.2.4, 10.4.2.6, 9eee38236f3bf28406920213d93981a3, and remote1 values in the above example with your actual values.

You provide credentials for the source cluster and information, including credentials and UUID for destination cluster. This will generate a request similar to the following sample:

POST /pools/default/remoteClusters HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
Content-Length: 114
Content-Type: application/x-www-form-urlencoded

If successful, Couchbase Server will respond with a JSON response similar to the following:

{"name":"remote1","uri":"/pools/default/remoteClusters/remote1",
"validateURI":"/pools/default/remoteClusters/remote1?just_validate=1",
"hostname":"10.4.2.6:8091",
"username":"Administrator",
"uuid":"9eee38236f3bf28406920213d93981a3",
"deleted":false}

The following describes the response elements:

  • (String) name: Name of the destination cluster referenced for XDCR.

  • (String) validateURI: URI to validate details of cluster reference.

  • (String) hostname: Hostname/IP (and :port) of the remote cluster.

  • (String) username: Username for the destination cluster administrator.

  • (String) uuid: UUID of the remote cluster reference.

  • (Boolean) deleted: Indicates whether the reference to the destination cluster has been deleted or not.

For more information about XDCR and creating references to destination clusters via the Couchbase Web Console, see Configuring Replication.

Deleting a destination cluster reference

You can remove a reference to destination cluster using the REST API. A destination cluster is a cluster to which you replicate data. After you remove it, it will no longer be available for replication via XDCR:

curl -v -X DELETE -u admin:password1 10.4.2.4:8091/pools/default/remoteClusters/remote1

Replace the admin, password1, 10.4.2.4, and remote1 values in the above example with your actual values.

This will send a request similar to the following example:

DELETE /pools/default/remoteClusters/remote1 HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZDE=
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*

If successful, Couchbase Server will respond with a 200 response as well as the string, ‘OK’:

HTTP/1.1 200 OK
Server: Couchbase Server 2.0.0-1941-rel-community
Pragma: no-cache

....

"ok"

For more information about XDCR and references to destination clusters via the Couchbase Web Console, see Configuring Replication.

Creating XDCR replications

To replicate data to an established destination cluster from a source cluster, you can use the REST API or Couchbase Web Console. Once you create a replication it will automatically begin between the clusters. As a REST call:

curl -v -X POST -u admin:password1 http://10.4.2.4:8091/controller/createReplication
    -d fromBucket=beer-sample
    -d toCluster=remote1
    -d toBucket=remote_beer
    -d replicationType=continuous
    -d type=capi

Replace the admin, password1, 10.4.2.4, beer-sample, remote1, remote_beer, and capi values in the above example with your actual values. The replicationType must be continuous. The type values are capi or xmem where capi and xmem are represented by version1 and version 2 in the web console. Default: xmem.

This will send a request similar to the following example:

POST / HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZDE=
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
Content-Length: 126
Content-Type: application/x-www-form-urlencoded

If Couchbase Server successfully creates the replication, it will immediately begin replicating data from the source to destination cluster. You will get a response similar to the following JSON:

{
  "id": "9eee38236f3bf28406920213d93981a3/beer-sample/remote_beer",
  "database": "http://10.4.2.4:8092/_replicator"
}

The unique document ID returned in the JSON is a reference you can use if you want to delete the replication.

For more information about XDCR and creating a new replication see Configuring Replication.

Deleting XDCR replications

When you delete a replication, it stops replication from the source to the destination. If you re-create the replication between the same source and destination clusters and buckets, it XDCR will resume replication. To delete replication via REST API:

curl -u admin:password1  \
http://10.4.2.4:8091/controller/cancelXDCR/9eee38236f3bf28406920213d93981a3%2Fbeer-sample%2Fremote_beer  \
-X DELETE

Replace the admin, password1, 10.4.2.4, 9eee38236f3bf28406920213d93981a3, beer-sample, and remote_beer values in the above example with your actual values.

You use a URL-encoded endpoint which contains the unique document ID that references the replication. You can also delete a replication using the Couchbase Web Console. For more information, see Configuring Replication.

Viewing internal XDCR settings

There are internal settings for XDCR which are only exposed via the REST API. These settings will change the replication behavior, performance, and timing. To view an XDCR internal settings, for instance:

curl -u admin:password1  \
http://10.4.2.4:8091/internalSettings

Replace the admin, password1, and 10.4.2.4 values in the above example with your actual values.

You will receive a response similar to the following. For the sake of brevity, we are showing only the XDCR-related items:

{
....

"xdcrMaxConcurrentReps":33,
"xdcrCheckpointInterval":222,
"xdcrWorkerBatchSize":555,
"xdcrDocBatchSizeKb":999,
"xdcrFailureRestartInterval":44
....
}

For more information about these settings and their usage, see Cross Datacenter Replication (XDCR), Providing Advanced Settings.

Changing internal XDCR settings

There are internal settings for XDCR which will change the replication behavior, performance, and timing. With the Couchbase Server, endpoints are available to change global settings for replications for a cluster and to change settings for a specific replication ID:

  • /settings/replications/ — global settings applied to all replications for a cluster
  • /settings/replications/<replication_id> — settings for specific replication for a bucket
  • /internalSettings - settings applied to all replications for a cluster. Endpoint exists in Couchbase 2.0 and onward.

As of Couchbase Server 2.2+ you can change settings for a specific replication ID in Web Console | XDCR | Ongoing Replications | Settings. In the REST API you can change these settings globally for all replications for a cluster or for a specific replication ID. For detailed information about these settings including the impact of changes to a setting, see XDCR, Providing Advanced Settings:

Parameter Value Description
xdcrMaxConcurrentReps Integer Equivalent to Web Console setting XDCR Max Replications per Bucket.
xdcrCheckpointInterval Integer Same as Web Console settingXDCR Checkpoint Interval.
xdcrWorkerBatchSize Integer Known as Web Console setting XDCR Batch Count.
xdcrDocBatchSizeKb Integer Same as Web Console setting XDCR Batch Size (KB).
xdcrFailureRestartInterval Integer equal to Web Console settingXDCR Failure Retry Interval.
xdcrOptimisticReplicationThreshold Integer Same as to Web Console setting XDCR Optimistic Replication Threshold.

There are additional internal settings for XDCR which are not yet exposed by Web Console, but are available via the REST API. These parameters are as follows:

Parameter Value Description
workerProcesses Integer from 1 to 32. Default 32. The number of worker processes for each vbucket replicator in XDCR. Setting is available for replications using either memcached or REST for replication.
httpConnections Integer from 1 to 100. Default 2. Number of maximum simultaneous HTTP connections used for REST protocol.

The following example updates an XDCR setting for parallel replication streams per node:

curl -X POST -u admin:password1  \
http://10.4.2.4:8091/settings/replications/  \
-d xdcrMaxConcurrentReps=64

Replace the admin, password1, 10.4.2.4, and 64 values in the above example with your actual values.

If Couchbase Server successfully updates this setting, it will send a response as follows:

HTTP/1.1 200 OK
Server: Couchbase Server 2.0.0-1941-rel-community
Pragma: no-cache
Date: Wed, 28 Nov 2012 18:20:22 GMT
Content-Type: application/json
Content-Length: 188
Cache-Control: no-cache

Getting XDCR stats via REST

You can get XDCR statistics from either Couchbase Web Console, or the REST API. You perform all of these requests on a source cluster to get information about a destination cluster. All of these requests use the UUID, a unique identifier for destination cluster. You can get this ID by using the REST API if you do not already have it. For instructions, see Getting a Destination Cluster Reference. The endpoints are as follows:



http://hostname:port/pools/default/buckets/[bucket_name]/stats/[destination_endpoint]

# where a possible [destination endpoint] includes:

# number of documents written to destination cluster via XDCR
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_written

# size of data replicated in bytes
replications/[UUID]/[source_bucket]/[destination_bucket]/data_replicated

# number of updates still pending replication
replications/[UUID]/[source_bucket]/[destination_bucket]/changes_left

# number of documents checked for changes
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_checked

# number of checkpoints issued in replication queue
replications/[UUID]/[source_bucket]/[destination_bucket]/num_checkpoints

# number of checkpoints failed during replication
replications/[UUID]/[source_bucket]/[destination_bucket]/num_failedckpts

# size of replication queue in bytes
replications/[UUID]/[source_bucket]/[destination_bucket]/size_rep_queue

# active vBucket replicators
replications/[UUID]/[source_bucket]/[destination_bucket]/active_vbreps

# waiting vBucket replicators
replications/[UUID]/[source_bucket]/[destination_bucket]/waiting_vbreps

# seconds elapsed during replication
replications/[UUID]/[source_bucket]/[destination_bucket]/time_committing

# time working in seconds including wait time
replications/[UUID]/[source_bucket]/[destination_bucket]/time_working

# bandwidth used during replication
replications/[UUID]/[source_bucket]/[destination_bucket]/bandwidth_usage

# aggregate time waiting to send changes to destination cluster in milliseconds
# weighted average latency for sending replicated changes to destination cluster
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_latency_aggr
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_latency_wt

# Number of documents in replication queue
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_rep_queue

# aggregate time to request and receive metadata about documents
# weighted average time for requesting document metadata
# XDCR uses this for conflict resolution prior to sending document into replication queue
replications/[UUID]/[source_bucket]/[destination_bucket]/meta_latency_aggr
replications/[UUID]/[source_bucket]/[destination_bucket]/meta_latency_wt

# bytes replicated per second
replications/[UUID]/[source_bucket]/[destination_bucket]/rate_replication
# number of docs sent optimistically 
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_opt_repd

You need to provide properly URL-encoded /[UUID]/[source_bucket]/[destination_bucket]/[stat_name]. To get the number of documents written:

curl -u admin:password http://localhost:8091/pools/default/buckets/default/stats/replications%2F8ba6870d88cd72b3f1db113fc8aee675%2Fsource_bucket%2Fdestination_bucket%2Fdocs_written

Replace the admin, password, localhost, 8ba6870d88cd72b3f1db113fc8aee675, source_bucket, and destination_bucket values in the above example with your actual values.

The above command produces the following output:

{"samplesCount":60,"isPersistent":true,"lastTStamp":1371685106753,"interval":1000,
"timestamp":[1371685048753,1371685049754,1371685050753,1371685051753,1371685052753,1371685053753,1371685054753,
1371685055753,1371685056753,1371685057753,1371685058752,1371685059753,1371685060753,1371685061753,1371685062753,
1371685063753,1371685064753,1371685065753,1371685066753,1371685067753,1371685068753,1371685069753,1371685070753,
1371685071753,1371685072753,1371685073753,1371685074753,1371685075753,1371685076753,1371685077753,1371685078753,
1371685079753,1371685080753,1371685081753,1371685082753,1371685083753,1371685084753,1371685085753,1371685086753,
1371685087753,1371685088753,1371685089753,1371685090753,1371685091754,1371685092753,1371685093753,1371685094753,
1371685095753,1371685096753,1371685097753,1371685098753,1371685099753,1371685100753,1371685101753,1371685102753,
1371685103753,1371685104753,1371685105753,1371685106753],
"nodeStats":{"127.0.0.1:8091":[1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000]}}

This shows that XDCR transferred 1 million documents at each of the timestamps provided. To get the rate of replication, make this REST request:

curl -u admin:password http://localhost:8091/pools/default/buckets/default/stats/replications%2F8ba6870d88cd72b3f1db113fc8aee675%2Fsource_bucket%2Fdestination_bucket%2Frate_replication

Replace the admin, password, localhost, 8ba6870d88cd72b3f1db113fc8aee675, source_bucket, and destination_bucket values in the above example with your actual values.

This will produce the following output:

{"samplesCount":60,"isPersistent":true,"lastTStamp":1371685006753,"interval":1000,
"timestamp":[1371684948753,1371684949753,1371684950753,1371684951753,1371684952753,1371684953753,1371684954753,
1371684955754,1371684956753,1371684957753,1371684958753,1371684959753,1371684960753,1371684961753,1371684962753,
1371684963753,1371684964753,1371684965753,1371684966753,1371684967753,1371684968752,1371684969753,1371684970753,
1371684971753,1371684972753,1371684973753,1371684974753,1371684975753,1371684976753,1371684977753,1371684978753,
1371684979753,1371684980753,1371684981753,1371684982753,1371684983753,1371684984753,1371684985754,1371684986753,
1371684987754,1371684988753,1371684989753,1371684990753,1371684991753,1371684992753,1371684993753,1371684994753,
1371684995753,1371684996753,1371684997753,1371684998776,1371684999753,1371685000753,1371685001753,1371685002753,
1371685003753,1371685004753,1371685005753,1371685006753],
"nodeStats":{"127.0.0.1:8091":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}}

To get docs_opt_repd you first get the replication id for a source and destination bucket. First get a list active tasks for a cluster:

    curl -s -u admin:password \
    http://localhost:8091/pools/default/tasks

Replace the admin, password, and localhost values in the above example with your actual values.

This will result in output as follows:

    ....
    "id": "def03dbf5e968a47309194ebe052ed21\/bucket_source\/bucket_destination", 
    "source": "bucket_source",
    "target":"\/remoteClusters\/def03dbf5e968a47309194ebe052ed21\/buckets\/bucket_name", 
    "continuous": true, 
    "type": "xdcr", 
    ....

With this replication id you can get a sampling of stats for docs_opt_repd:

http://10.3.121.119:8091/pools/default/buckets/default/stats/ \
replications%2fdef03dbf5e968a47309194ebe052ed21%2fbucket_source%2fbucket_destination%2fdocs_opt_repd 

This results in output similar to the following:

    { 
       "samplesCount":60, 
       "isPersistent":true, 
       "lastTStamp":1378398438975, 
       "interval":1000, 
       "timestamp":[ 
          1378398380976, 
          1378398381976,
          ....

You can also see the incoming write operations that occur on a destination cluster due to replication via XDCR. For this REST request, you need to make the request on your destination cluster at the following endpoint:

http://[Destination_IP]:8091/pools/default/buckets/[bucket_name]/stats

This returns results for all stats as follows. Within the JSON you find an array xdc_ops and the value for this attribute will be the last sampling of write operations on the destination due to XDCR:

{
.................
"xdc_ops":[0.0,0.0,0.0,0.0,633.3666333666333,1687.6876876876877, \
2610.3896103896104,3254.254254254254,3861.138861138861,4420.420420420421, \
................
}

Many of these statistics are exposed in the Couchbase Web Console. For more information, see Monitoring Outgoing XDCR.

Managing XDCR data encryption

The process for configuring XDCR with data encryption (Enterprise Edition only) involves configuring the XDCR cluster reference with data encryption enabled, providing the SSL certificate, and configuring replication.

The following summarizes the HTTP methods used for defining XDCR data encryption:

HTTP method URI path Description
GET /pools/default/remoteClusters Gets the destination cluster reference
POST /pools/default/remoteClusters Creates a reference to the destination cluster
PUT /pools/default/remoteClusters/UUID Modifies the destination cluster reference
DELETE /pools/default/remoteClusters/UUID Deletes the reference to the destination cluster.

Retrieving certificates

To retrieve the SSL certificate from the destination cluster to the source cluster:

Destination endpoint

/pools/default/certificate

Example

curl http://remoteHost:port/pools/default/certificate > ./remoteCert.pem

Regenerating certificates

To regenerate a certificate on a destination cluster:

Destination endpoint

/controller/regenerateCertificate

Example

curl -X POST http://Administrator:asdasd@remoteHost:8091/controller/regenerateCertificate

Configuring XDCR with data encryption

A POST to /pools/default/remoteClusters creates the XDCR cluster reference from the source cluster to the destination cluster. Setting the demandEncryption to one (1) and providing the certificate name and location enables data encryption.

Destination endpoint

POST /pools/default/remoteClusters creates the destination cluster reference.

PUT /pools/default/remoteClusters modifies the destination cluster reference.

Syntax

curl –X POST  -u Admin:myPassword
  http://localHost:port/pools/default/remoteClusters 
  -d name=<clusterName>             // Remote cluster name
  -d hostname=<host>:<port>         // FQDN of the remote host.
  -d username=<adminName>           // Remote cluster Admin name
  -d password=<adminPassword>       // Remote cluster Admin password
  -d demandEncryption=[0|1] --data-urlencode "certificate=$(cat remoteCert.pem)"

Example

curl –X POST 
-d name=remoteName  
-d hostname=10.3.4.187:8091
-d username=remoteAdmin –d password=remotePassword
-d demandEncryption=1 --data-urlencode "certificate=$(cat remoteCert.pem)"
http://Administrator:asdasd@192.168.0.1:8091/pools/default/remoteClusters/

Disabling data encryption

To modify the XDCR configuration so that SSL data encryption is disabled, execute a PUT from the source cluster to the destination cluster with demandEncryption=0.

Destination endpoint

/pools/default/remoteClusters

Example

curl –X PUT  -u Admin:myPassword
  http://192.168.0.1:8091/pools/default/remoteClusters/
-d name=remoteName 
-d hostname=10.3.4.187:8091
-d username=remoteAdmin –d password=remotePassword
-d demandEncryption=0

Compaction REST API

Set data and index compaction

Couchbase Server will write all data that you append, update and delete as files on disk. This process can eventually lead to gaps in the data file, particularly when you delete data. Be aware the server also writes index files in a sequential format based on appending new results in the index. You can reclaim the empty gaps in all data files by performing a process called compaction. In both the case of data files and index files, you will want to perform frequent compaction of the files on disk to help reclaim disk space and reduce disk fragmentation. For more general information on this administrative task, see Database and View Compaction.

Compacting bucket data and indexes

To compact data files for a given bucket as well as any indexes associated with that bucket, you make this request:

curl -i -v -X POST -u admin:password http://localhost:8091/pools/default/buckets/bucket_name/controller/compactBucket

Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.

Where you provide the ip and port for a node that accesses the bucket as well as the bucket name. You need to provide administrative credentials for that node in the cluster. To stop bucket compaction, issue this request:

curl -i -v -X POST -u admin:password http://localhost:8091/pools/default/buckets/bucket_name/controller/cancelBucketCompaction

Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.

Compacting spatial views

If you have spatial views in your dataset, these are not automatically compacted with data and indexes. Instead, you must manually compact each spatial view through the REST API.

To do this, you must call the spatial compaction endpoint:

http://127.0.0.1:9500/BUCKETNAME/_design/DDOCNAME/_spatial/_compact

This URL contains the following special information:

  • 127.0.0.1:9500

    The port number, 9500, is unique to the spatial indexing system.

  • BUCKETNAME

    The BUCKETNAME is the name of the bucket in which the design document is configured.

  • DDOCNAME

    The name of the design document that contains the spatial index or indexes that you want to compact.

For example, you can send a request using curl :

curl -u admin:password -X POST \
'http://localhost:8091/default/_design/dev_test_spatial_compaction/_spatial/_compact'
-H 'Content-type: application/json'

Replace the admin, password, and localhost values in the above example with your actual values.

Setting auto-compaction

In Couchbase Server you can also provide auto-compaction settings which will trigger data and view compaction based on certain settings. These settings can be made for an entire cluster or for a bucket in a cluster. For background information, see Admin Tasks, Compaction Process. To details about each setting, see Admin Tasks, Auto-Compaction Configuration

Auto-compaction API

REST API Description
POST /controller/setAutoCompaction Set cluster-wide auto-compaction intervals and thresholds
GET /settings/autoCompaction Read cluster-wide settings for auto-compaction
GET /pools/default/buckets/bucket_name Read auto-compaction settings for named bucket
POST/pools/default/buckets/bucket_name Set auto-compaction interval or thresholds for named bucket

Auto-compaction parameters

You can use the following parameters for global auto-compaction settings which apply to all buckets in a cluster at /controller/setAutoCompaction. You also use these at /pools/default/buckets/<bucket_name>
for bucket-level auto-compaction. You will need to provide administrative credentials to change these settings.

As of Couchbase Server 2.2+ you can provide a purge interval to remove the key and metadata for items that have been deleted or are expired. This is known as ‘tombstone purging’. For background information, see Introduction, Tombstone Purging.

Parameter Value Notes
databaseFragmentationThreshold[percentage] Integer between 2 and 100 Percentage disk fragmentation for data
databaseFragmentationThreshold[size] Integer greater than 1 Bytes of disk fragmentation for data
viewFragmentationThreshold[percentage] Integer between 2 and 100 Percentage disk fragmentation for index
viewFragmentationThreshold[size] Integer greater than 1 Bytes of disk fragmentation for index
parallelDBAndViewCompaction True or false Run index and data compaction in parallel
allowedTimePeriod[fromHour] Integer between 0 and 23 Compaction can occur from this hour onward
allowedTimePeriod[toHour] Integer between 0 and 23 Compaction can occur up to this hour
allowedTimePeriod[fromMinute] Integer between 0 and 59 Compaction can occur from this minute onward
allowedTimePeriod[toMinute] Integer between 0 and 59 Compaction can occur up to this minute
allowedTimePeriod[abortOutside] True or false Terminate compaction if process takes longer than allowed time
purgeInterval Integer between 1 and 60 Number of days a item is deleted or expired. The key and metadata for that item will be purged by auto-compaction

To read current auto-compaction settings for a cluster:

    curl -u admin:password http://localhost:8091/settings/autoCompaction

Replace the admin, password, and localhost values in the above example with your actual values.

This will result in JSON response as follows:

    {
       "purgeInterval": 3,
       "autoCompactionSettings": {
           "viewFragmentationThreshold": {
               "size": "undefined",
               "percentage": "undefined"
            },
            "databaseFragmentationThreshold": {
                "size": "undefined",
                "percentage": "undefined"
            },
         "parallelDBAndViewCompaction": false
       }
    }

This tells us we have a purgeInterval of three days and no current thresholds set for data or index compaction. The field parallelDBAndViewCompaction set to ‘false’ indicates the cluster will not perform data and index compaction in parallel. To see auto-compaction settings for a single bucket, use this request:

    curl -u admin:password http://localhost:8091/pools/default/buckets/bucket_name

Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.

Couchbase Server sends a JSON response with auto-compaction settings for the bucket_name:

{
    "purgeInterval": 2,
    "autoCompactionSettings": {
        "viewFragmentationThreshold": {
            "size": "undefined",
            "percentage": 30
        },
        "databaseFragmentationThreshold": {
            "size": "undefined",
            "percentage": 30
        },
        "parallelDBAndViewCompaction": true
    }
}

This indicates a tombstone purgeInterval of two days with a threshold of 30% disk fragmentation for data and views. This means items can be expired for two days or deleted two ago and their tombstones will be purged during the next auto-compaction run.cluster-wide

Logs REST API

This section provides the REST API endpoints for retrieving log and diagnostic information as well as how an SDK can add entries into a log.

HTTP method URI path Description
GET /diag Retrieves log and additional server diagnostic information.
GET /sasl_logs Retrieves log information.

Retrieving log information

Couchbase Server logs various messages, which are available via the REST API. These log messages are optionally categorized by the module. A generic list of log entries or log entries for a particular category can be retrieved.

Note

If the system is secured, administrator credentials are required to access logs.

To retrieve log and server diagnostic information, perform a GET with the /diag endpoint.

curl -v -X GET -u Administrator:password
   http://127.0.0.1:8091/diag

To retrieve a generic list of logs, perform a GET with the /sasl_logs endpoint.

curl -v -X GET -u Administrator:password 
  http://127.0.0.1:8091/sasl_logs

To retrieve a specific log file, perform a GET on the sasl_logs endpoint and provide a specific log category.

curl -v -X GET -u Administrator:password
 http://127.0.0.1:8091/sasl_logs/<logName>

Where the logName is one of the following log types:

  • babysitter
  • couchdb
  • debug
  • error
  • info
  • mapreduce_errors
  • ssl_proxy
  • stats
  • view
  • xdcr
  • xdcr_errors

Example

curl -v -X GET -u Administrator:password
 http://127.0.0.1:8091/sasl_logs/ssl_proxy

Results

* About to connect() to 10.5.2.118 port 8091 (#0)
*   Trying 10.5.2.118... connected
* Connected to 10.5.2.118 (10.5.2.118) port 8091 (#0)
* Server auth using Basic with user 'Administrator'
> GET /sasl_logs/ssl_proxy HTTP/1.1
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.21.4 (x86_64-unknown-linux-gnu) libcurl/7.21.4 OpenSSL/0.9.8b zlib/1.2.3
> Host: 10.5.2.118:8091
> Accept: */*
> 
< HTTP/1.1 200 OK
< Transfer-Encoding: chunked
< Server: Couchbase Server
< Pragma: no-cache
< Date: Thu, 06 Feb 2014 22:50:12 GMT
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
< 
logs_node (ssl_proxy):
-------------------------------
[ns_server:info,2014-01-24T11:25:18.066,nonode@nohost:<0.30.0>:ns_ssl_proxy:init_logging:84]Brought up ns_ssl_proxy logging
[error_logger:info,2014-01-24T11:25:18.082,nonode@nohost:error_logger<0.5.0>:ale_error_logger_handler:log_report:72]
=========================PROGRESS REPORT=========================
          supervisor: {local,ns_ssl_proxy_sup}
             started: [{pid,<0.64.0>},
                       {name,ns_ssl_proxy_server_sup},
                       {mfargs,{ns_ssl_proxy_server_sup,start_link,[]}},
                       {restart_type,permanent},
                       {shutdown,infinity},
                       {child_type,supervisor}]

Creating a client logging interface

Entries can be added to the central log from a custom Couchbase SDK. These entries are typically responses to exceptions such as difficulty handling a server response. For instance, the Web Console uses this functionality to log client error conditions.

To add entries, provide a REST request similar to the following:

POST /logClientError
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
200 - OK

Users REST API

As of Couchbase Server 2.2+ you can create one read-only user with the REST API. For more information about this type of user, see Read-Only Users.

To create a read-only user, you need administrative access:

curl -X POST -u admin:password http://localhost:8091/settings/readOnlyUser -d username=a_name -d password=a_password 

Replace the admin, password, localhost, a_name, and a_password values in the above example with your actual values.

Upon success, you will get this response:

success: 200 | []

The endpoint has one additional, optional parameter just_validate=1. If you provide this in your request the server will validate the username and password for a read-only user but will not actually create the user.

The following are the endpoints, parameters, expected return values and possible errors:

Request Description Parameters Returns Errors
POST /settings/readOnlyUser Create read-only user username, password, just_validate success: 200 [] error: 400 | {“errors”:{field_name:error_message}}
PUT /settings/readOnlyUser Change read-only user password password success: 200 [] error: 400 | {“errors”:{field_name:error_message}}
DELETE /settings/readOnlyUser Delete user none success: 200 [] error: 400 | {“errors”:{field_name:error_message}}
GET /settings/readOnlyAdminName Get the read-only username none success: 200 “username” not found: 404

A username is a UTF-8 string that does not contain spaces, control characters or any of these characters: ()<>@,;:\\“/[]?={} characters. Any password must be UTF-8 with no control characters and must be at least six characters long.

To change the password for a read-only user:

curl -X POST -u admin:password http://localhost:8091/settings/readOnlyUser -d username=a_name -d password=new_password

To delete this user:

curl -X DELETE -u admin:password http://localhost:8091/settings/readOnlyUser 

To get the read-only username, you can have administrative or read-only permissions:

curl -u username:password  http://localhost:8091/settings/readOnlyAdminName

Replace the admin, password, localhost, username, a_name, and new_password values in the above examples with your actual values.

This will return a response with the read-only username as payload, success: 200 | "username". If there is no read-only user you will get this error not found: 404.