Description

Buckets are created and edited with a POST sent to the REST URI endpoint for buckets in a cluster. This can be used to create either a Couchbase or a Memcached type bucket. Bucket names cannot have a leading underscore.

This endpoint is also used to get a list of buckets that exist for a cluster.

The REST API returns a successful response when preliminary files for a data bucket are created on one node. However, if a multi-node cluster is implemented, bucket creation may not have completed 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 verify that a bucket is available, try to read a key from the bucket. If a ‘key not found’ error is received or the document for the key is returned, then the bucket exists and is available to all nodes in a cluster. Key requests can be issued via a Couchbase SDK with any node in the cluster. See the Couchbase Developer Guide for more information.

HTTP method and URI

POST /pools/default/buckets

• Request data - List of payload parameters for the new bucket
• Response data - JSON of the bucket confirmation or an error condition
• Authentication required - Yes

Parameters for creating buckets:

When creating a bucket, the authType parameter must be provided:

• If authType is set to none, then a proxyPort number must be specified.

• If authType is set to sasl, then the saslPassword parameter may optionally be specified.

The ramQuotaMB parameter specifies how much memory, in megabytes, is 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 evicts items on a least-requested-item basis. Couchbase Server might evict other infrequently used items depending on object size or on whether or not an item is being referenced.

• In the case of Couchbase buckets, the system might return temporary failures if the ramQuotaMB is reached. The system tries 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 are retrieved from disk.

Syntax

Curl request syntax:

curl -X POST -u [admin]:[password] 
	-d name=[new-bucket-name] -d ramQuotaMB=[value] -d authType=[none | sasl] \
	-d replicaNumber=[value] -d proxyPort=[proxy-port] 
	http://[localhost]:8091/pools/default/buckets
			

Example

Curl request example:

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

Raw HTTP request example:

The parameters for configuring the bucket are provided as payload data. Each parameter and value are provided as a key/value pair where each pair is separated by an ampersand. Include the parameters setting in the payload of the HTTP POST request.

POST /pools/default/buckets
HTTP/1.1
Host: 10.5.2.54: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

Response

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

202 Accepted

Response codes

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