Membase Manual 1.7 - Chapter 4. Membase Administration

4.3.1. Key Concepts
Prev	4.3. Membase Management REST API	Next

4.3.1. Key Concepts

4.3.1. Resources
4.3.1. Pools/Clusters
4.3.1. Server Nodes
4.3.1. HTTP Request Headers
4.3.1. HTTP Status Codes

In order to use the REST API you should be aware of the different terms and concepts highlighted in this section.

Resources

There are a number of different resources within the Membase Server and these resources can optionally have one or more controllers, which have RESTful endpoints in the representation of the item one would control.

Pools/Clusters

A pool (or cluster) is a collection of physical resources that are grouped together and provide services and a management interface. A single, default pool exists for every deployment of Membase Server. A Node (server node) is a member of a pool. Membase Server collects run-time statistics for pools, maintaining an overall pool-level data view of counters and periodic metrics of the overall system. The Membase Management REST API can be used to retrieve historic statistics for pools.

Server Nodes

A Server Node is a physical or virtual machine running Membase Server as a member of a pool.

Data Buckets

A data bucket is a logical grouping of resources within a pool. In support of pool and resource management, a bucket provides unconstrained namespaces to users to define whatever bucket name makes sense to the user. It also allows the same key in the same application to be available in multiple places.

Membase 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. Buckets can implement different kinds of behaviors, such as cache only or persisted (either synchronous or asynchronous) key-value stores.

HTTP Request Headers

The following HTTP request headers are supported when making requests to any URI within the REST API. The request headers are validated server-side during requests.

Table 4.4. Supported Request Headers

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 Membase Management REST API returns the following standard HTTP response codes under the conditions explained in the associated description.

Table 4.5. HTTP Status Codes

HTTP Status	Description
200 OK	The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a Location header containing the canonical URI for the newly created resource.
201 Created	A request that created a new resource was completed, and no response body containing a representation of the new resource is being returned. A Location header containing the canonical URI for the newly created resource should also be returned.
202 Accepted	The request has been accepted for processing, but the processing has not been completed. Per the HTTP/1.1 specification, the returned entity (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 user can expect the request to be fulfilled.
204 No Content	The server fulfilled the request, but does not need to return a response message 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 authentication credentials included with this request are missing or invalid.
403 Forbidden	The server recognized your credentials, but you do not possess authorization to perform this request.
404 Not Found	The request specified a URI of a resource that does not exist.
405 Method Not Allowed	The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
406 Not Acceptable	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
409 Conflict	A creation 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.

Operations

This section describes Membase Management REST API operations.

Launching the Membase Web Console

The Membase Web Console loads and runs in a common Web Browser user agent. It consists of HTML pages, images, CSS, and JavaScript. For a list of supported browsers, see Getting Started#System Requirements. For the Membase Web Console, a separate UI hierarchy is served from each node of the system (though asking for the root "/" would likely return a redirect to the user agent). To launch the Membase Web Console, point your browser to the appropriate host and port:

GET https://node.in.pool.com/

Bootstrapping

Clients must bootstrap to gain an entry point into the RESTful service. Bootstrapping requires looking for pools, as shown in the request blow. The URI space, in Membase's implementation may appear to have very specific URI and in some ways may even appear as RPC or some other architectural style using HTTP operations and semantics. That is only an artifact of the URIs Membase chose. Clients are advised to be properly RESTful and will not expect to receive any handling instructions resource descriptions or presume any conventions on URI structure for resources represented. Also note that the hierarchies shown here can allow reuse of agent handling of representations, since they are similar for different parts of the hierarchy.

Request

GET /pools
Host: node.in.your.pool.com
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1

Response

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


{
  "implementationVersion": "253",
  "pools" : [
    {
      "name": "Default Pool",
      "uri": "/pools/default",
    },
    {
      "name": "Membase kvcaching pool name",
      "uri": "/pools/anotherpool",
    },
    {
      "name": "A pool elsewhere",
      "uri": "https://a.node.in.another.pool.com:4321/pools/default"
    }
  ]
  "uri": "https://node.in.your.pool.com/pools",
  "specificationVersion": [
    "0.1"
  ]
}

Only one pool per group of systems will be known and it will likely be defaulted to a name. POSTing back a changed pool will return a 403.

As can be seen, the "build" number of the implementation is apparent in the implementation_version, the specifications supported are apparent in the specification_version. While this node can only be a member of one pool, 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 to adjust representation and state transitions to the client, if backward compatibility is desirable.

Provisioning a Node

Before a node can be used in a cluster, a few things may need to be configured. Specifically, if creating a new cluster, the memory quota per node for that cluster must be set. Whether the node is joining an existing cluster or starting a new cluster, it's storage path must be configured.

Either creating a new cluster or adding a node to a cluster is referred to as provisioning, and has several steps required. After bootstrapping the following will need to be accomplished.

Configure the node's disk path.
Configure the cluster's memory quota. This is optional. It will inherit the memory quota if the node is to be joined to a cluster and it will default to 80% of physical memory if not specified.

The next step depends on whether a new cluster is being created or an existing cluster will be joined. If a new cluster is to be created, it will need

to be "secured" by providing a username and password for the administrator. If the node is to be joined to another cluster, then it will need the location and credentials to the REST interface of that cluster.

Configuring the disk path for a node

Node resources can be configured through a controller on the node. The primary resource to be configured is the path on the node for persisting files. This must be configured prior to creating a new cluster or configuring the node into an existing cluster.

Request

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

Response

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

Example

shell> curl -d path=/var/tmp/test http://localhost:8091/nodes/self/controller/settings

Configuring a cluster's memory quota Request

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

Response

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

Example

shell> curl -d memoryQuota=400 http://localhost:8091/pools/default

Setting a node's username and password

While this can be done at any time for a cluster, it is the last step in provisioning a node into being a new cluster. The response will indicate the new base URI if the parameters are accepted. Clients will want to re-bootstrap based on this response.

Request Response

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

HTTP/1.1 200 OK Content-Type: application/json Server: Membase Server 1.6.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/"}

Example

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

Note

Note that even if it is not to be changed, the port number must be specified.

Global settings

Setting whether statistics should be sent to the outside or not

It's a global setting for all clusters. You need to be authenticated to change this value.

Request

POST /settings/stats HTTP/1.1 Host: node.in.your.cluster:8091 Content-Type: application/x-www-form-urlencoded Authorization: Basic YWRtaW46YWRtaW4= Content-Length: 14 sendStats=true

Response

200 OK 400 Bad Reqeust, The value of "sendStats" must be true or false. 401 Unauthorized

Example

curl -i -u Administrator:letmein -d sendStats=true http://localhost:8091/settings/stats

Getting whether statistics should be sent to the outside or not

It's a global setting for all clusters. You need to be authenticated to read this value.

Request

GET /settings/stats HTTP/1.1 Host: node.in.your.pool.com Authorization: Basic YWRtaW46YWRtaW4= Accept: */*

Response

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

Example

curl -u Administrator:letmein http://localhost:8091/settings/stats

Setting whether auto-failover should be enabled or disabled

This endpoint isn't available yet.

It's a global setting for all clusters. You need to be authenticated to change this value.

Possible parameters are:

enabled (true|false) (required): whether to enable or disable auto-failover
timeout (integer biger (or equal) than 30) (required; optional when enabled=false): The number of seconds a node must be down before it is automatically failovered

Request

POST /settings/autoFailover HTTP/1.1 Host: node.in.your.cluster:8091 Content-Type: application/x-www-form-urlencoded Authorization: Basic YWRtaW46YWRtaW4= Content-Length: 14 enabled=true&timeout=60

Response

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

Example

curl -i -u Administrator:letmein -d enabled=true&timeout=60http://localhost:8091/settings/autoFailover

Getting information about the auto-failover settings

This endpoint isn't available yet.

It's a global setting for all clusters. You need to be authenticated to read this value.

Request Response

GET /settings/autoFailover HTTP/1.1 Host: node.in.your.pool.com Authorization: Basic YWRtaW46YWRtaW4= Accept: */*

HTTP/1.1 200 OK Content-Type: application/json Content-Length: nnn { "enabled": true, "timeout": 60, "count": 0 }

Example

curl -u Administrator:letmein http://localhost:8091/settings/autoFailover

Reset the auto-failover count

This endpoint isn't available yet.

It's a global setting for all clusters. You need to be authenticated to change this value. Reset the number of nodes that where automatically failovered to zero. No parameters

Request

POST /settings/autoFailover/resetCount HTTP/1.1 Host: node.in.your.cluster:8091 Content-Type: application/x-www-form-urlencoded Authorization: Basic YWRtaW46YWRtaW4=

Response

200 OK 401 Unauthorized

Example

curl -i -u Administrator:letmein http://localhost:8091/settings/autoFailover/resetCount

Setting whether email notification should be enabled or disabled

This endpoint isn't available yet.

It's a global setting for all clusters. You need to be authenticated to change this value.

You will receive an email when certain events happen (currently only events cause by auto-failover are supported).

Possible parameters are:

enabled (true|false) (required): whether to enable or disable email notifications
sender (string) (optional, default: membase@localhost): The sender address of the email
recipients (string) (required): A comma separated list of recipients of the of the alert 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'd like 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.

Request

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

Response

200 OK 400 Bad Request: JSON object ({"errors": {"key": "error"}}) with errors. Possible errors are:

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.
401 Unauthorized

Example

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

Getting information about the email notification settings

This endpoint isn't available yet.

It's a global setting for all clusters. You need to be authenticated to read this value.

Request

GET /settings/alerts HTTP/1.1 Host: node.in.your.pool.com Authorization: Basic YWRtaW46YWRtaW4= Accept: */*

Response Example

HTTP/1.1 200 OK Content-Type: application/json Content-Length: nnn { "alerts": [ "auto_failover_node", "auto_failover_maximum_reached" ], "emailServer": { "encrypt": false, "host": "localhost", "pass": "", "port": 25, "user": "" }, "enabled": true, "recipients": [ "user@localhost" ], "sender": "membase@localhost" }

curl -u Administrator:letmein http://localhost:8091/settings/alerts

Send test email

This endpoint isn't available yet.

It's a global setting for all clusters. You need to be authenticated to change this value. Sends a test email with the current configuration (see mail alerts section)

Takes the same parameters as /settings/alerts and additionally: subject (string) (required): The subject of the test email body (string) (required): The body of the test email

Request

POST /settings/alerts/sendTestEmail HTTP/1.1 Host: node.in.your.cluster:8091 Content-Type: application/x-www-form-urlencoded Authorization: Basic YWRtaW46YWRtaW4=

Response

200 OK 400 Bad Request: Unknown macro: {"error"} 401 Unauthorized

Example

curl -i -u Administrator:letmein http://localhost:8091/settings/alerts/sendTestEmail -d 'subject=Test+email+from+Membase&body=This+email+was+sent+to+you+to+test+the+email+alert+email+server+settings.&enabled=true&recipients=vmx%40localhost&sender=membase%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'

Pool Details

Request

GET /pools/default Host: node.in.your.pool.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/json X-memcachekv-Store-Client-Specification-Version: 0.1

Response

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@node.in.your.pool.com",
      "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"
      }
      }

At the highest level, a pool describes a cluster (as mentioned above). This cluster exposes a number of properties which define attributes of the cluster and "controllers" which allow users to make certain requests of the cluster.

Note that since buckets could be renamed and there is no way to determine what the default bucket for a pool is, the system will attempt to connect non-SASL, non-proxied to a bucket clients to a bucket named "default". If it does not exist, the connection will be dropped.

Clients MUST NOT rely on the node list here to create their "server list" for when connecting. They MUST instead issue an HTTP get call to the bucket to get the node list for that specific bucket.

The controllers, all of which accept parameters as x-www-form-urlencoded, for this list perform the following functions:

Table 4.6. Controller 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" (which is the admin user for the node), and "password".
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.

The list of nodes will list each node in the cluster. It will, additionally, list some attributes of the nodes.

Table 4.7. Node Attributes

Attribute	Description
memoryTotal	The total amount of memory available to Membase, allocated and free. May or may not be equal to the amount of memory configured in the system.
memoryFree	The amount of memory available to be allocated. This is equal to the memoryTotal, subtracting out all memory allocated as reported by the host operating system.
mcdMemoryReserved	The amount of memory reserved for use by Membase across all buckets on this node. This value does not include some overhead for managing items in the node or handling replication or other TAP streams.
mcdMemoryAllocated	The amount of memory actually used by all buckets on this node.

List Buckets and Bucket Operations

Clients to the system can choose to use either the proxy path or the direct path. If they use the direct path, they will not be insulated from most reconfiguration changes to the bucket. This means they will need to either poll the bucket's URI or connect to the streamingUri to receive updates when the bucket configuration changes. This happens, for instance, when nodes are added, removed, or may fall into an unhealthy state.

Request

GET /pools/default/buckets
Host: node.in.your.pool.com
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1

Response

HTTP/1.1 200 OK
Server: Membase 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": "membase",
        "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
        }
    }
]

Named Bucket and 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 above. 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.

Request

GET /pools/default/buckets/default
Host: node.in.your.pool.com
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1

Response

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

{
  "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": [
    {
      "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": 629145600
  },
  "basicStats": {
    "quotaPercentUsed": 14.706055058373344,
    "opsPerSec": 0,
    "diskFetches": 0,
    "itemCount": 65125,
    "diskUsed": 139132928,
    "memUsed": 277567495
  }
}

Flushing a Bucket

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.

Note

As of membase 1.6 bucket flushing via REST API is not supported. Flushing via memcached protocol works.

The bucket details provide a bucket URI at which a simple request can be made to flush the bucket.

Request

POST /pools/default/buckets/default/controller/doFlush Host: node.in.your.pool.com Authorization: Basic xxxxxxxxxxxxxxxxxxx X-memcachekv-Store-Client-Specification-Version: 0.1

Any parameters are accepted. Since the URI was defined by the bucket details, neither the URI nor the parameters control what is actually done by the service. The simple requirement is for a POST with an appropriate Authorization header, if the system is secured.

Response

204 No Content - if the flush is successful 404 Not Found - if the URI is invalid or does not correspond to a bucket the system is familiar with.

Deleting a Bucket

Warning

Request

DELETE /pools/default/buckets/default Host: node.in.your.pool.com Authorization: Basic xxxxxxxxxxxxxxxxxxx X-memcachekv-Store-Client-Specification-Version: 0.1

Response

Getting Statistics

Statistics can be gathered via the REST interface at the bucket level. Stats URL should be taken from stats.uri property of bucket response. By default it returns stats samples for last minute and hot keys. Via query parameters another zoom level can be requested.

zoom - stats zoom level (minute | hour | day | week | month | year)
resampleForUI - pass 1 if you need 60 samples
haveTStamp - request sending only samples newer than given timestamp

Request Response

GET /pools/default/stats Host: node.in.your.pool.com 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
      {
      "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 ],
      "ep_resident_items_rate": [ 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0 ],
      "ep_replica_resident_items_rate": [ 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0 ],
      "bytes_read": [ 151, 130, 72, 158, 120, 223, 103, 127, 127, 127,
      103, 130, 72, 158, 72, 220, 103, 175, 130, 127, 103, 127, 120,
      158, 72, 271, 103, 124, 130, 127, 103, 130, 72, 155, 72, 223, 103,
      124, 178, 127, 103, 130, 72, 206, 69, 223, 103, 175, 130, 127,
      103, 130, 72, 155, 72, 223, 103, 127, 130 ],
      "bytes_written": [ 36776, 40699, 15212, 41705, 15260, 41326,
      36728, 20360, 40658, 20388, 36728, 40699, 15212, 41705, 15212,
      41283, 36764, 20408, 40700, 20369, 36728, 40656, 15274, 41705,
      15212, 41374, 36728, 20338, 40700, 20388, 36728, 40699, 15212,
      41662, 15212, 41366, 36728, 20338, 40748, 20388, 36728, 40699,
      15212, 41753, 15195, 41326, 36728, 20408, 40739, 20369, 36728,
      40699, 15212, 41662, 15212, 41366, 36728, 20360, 40700 ],
      "cas_badval": [ 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 ],
      "cas_hits": [ 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 ],
      "cas_misses": [ 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 ],
      "cmd_get": [ 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 ],
      "cmd_set": [ 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 ],
      "curr_connections": [ 139, 139, 139, 139, 139, 139, 139, 139, 139,
      139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139,
      139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139,
      139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139,
      139, 139, 139, 139, 139, 139, 139, 139, 139, 139, 139 ],
      "curr_items": [ 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125 ],
      "curr_items_tot": [ 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250 ],
      "decr_hits": [ 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 ],
      "decr_misses": [ 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 ],
      "delete_hits": [ 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 ],
      "delete_misses": [ 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 ],
      "disk_writes": [ 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_bg_fetched": [ 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_flusher_todo": [ 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_io_num_read": [ 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_keys_size": [ 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_num_active_non_resident": [ 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_num_eject_replicas": [ 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_num_non_resident": [ 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_num_not_my_vbuckets": [ 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_num_value_ejects": [ 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_oom_errors": [ 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_overhead": [ 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200, 399200, 399200, 399200,
      399200, 399200, 399200, 399200, 399200 ],
      "ep_queue_size": [ 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_tap_bg_fetched": [ 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_tmp_oom_errors": [ 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_total_persisted": [ 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_values_size": [ 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
      ],
      "evictions": [ 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 ],
      "get_hits": [ 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 ],
      "get_misses": [ 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 ],
      "incr_hits": [ 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 ],
      "incr_misses": [ 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 ],
      "mem_used": [ 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950, 275869950, 275869950, 275869950, 275869950, 275869950,
      275869950 ],
      "misses": [ 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 ],
      "ops": [ 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 ],
      "replica_resident_items_tot": [ 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250, 130250,
      130250, 130250, 130250, 130250, 130250, 130250, 130250 ],
      "resident_items_tot": [ 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125,
      65125, 65125, 65125, 65125, 65125, 65125, 65125, 65125 ],
      "timestamp": [ 1292513719166.0, 1292513720166.0, 1292513721166.0,
      1292513722166.0, 1292513723166.0, 1292513724166.0,
      1292513725166.0, 1292513726166.0, 1292513727167.0,
      1292513728166.0, 1292513729166.0, 1292513730166.0,
      1292513731166.0, 1292513732166.0, 1292513733166.0,
      1292513734167.0, 1292513735166.0, 1292513736166.0,
      1292513737166.0, 1292513738166.0, 1292513739166.0,
      1292513740167.0, 1292513741166.0, 1292513742166.0,
      1292513743166.0, 1292513744166.0, 1292513745166.0,
      1292513746167.0, 1292513747167.0, 1292513748166.0,
      1292513749166.0, 1292513750166.0, 1292513751166.0,
      1292513752167.0, 1292513753167.0, 1292513754166.0,
      1292513755166.0, 1292513756167.0, 1292513757167.0,
      1292513758166.0, 1292513759166.0, 1292513760166.0,
      1292513761166.0, 1292513762166.0, 1292513763167.0,
      1292513764167.0, 1292513765167.0, 1292513766167.0,
      1292513767166.0, 1292513768166.0, 1292513769166.0,
      1292513770166.0, 1292513771166.0, 1292513772167.0,
      1292513773167.0, 1292513774166.0, 1292513775166.0,
      1292513776166.0, 1292513777166.0 ],
      "updates": [ 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": 1292513777166.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 } ] }

Managing Bucket Resources

A new bucket may be created with a POST command to the URI to the buckets defined URI for the pool. This can be used to create either a membase or a memcached type bucket. The bucket name cannot have a leading underscore.

When creating a bucket, an authType parameter must be specified:

If the authType is "none". then a proxyPort number MUST be specified.
If the authType is "sasl". then a "saslPassword" parameter MAY be optionally specified.

The ramQuotaMB attribute allows the user to specify how much memory (in megabytes) will be allocated on each node for the bucket.

In the case of memcached buckets, going beyond the ramQuotaMB will cause an item to be evicted on a mostly-LRU basis. The type of item evicted may not be the exact LRU due to object size, whether or not it is currently being referenced or other situations.
In the case of membase 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.

Creating a memcached Bucket

Request

POST /pools/default/buckets HTTP/1.1 Host: node.in.your.cluster:8091 Content-Type: application/x-www-form-urlencoded; charset=UTF-8 Authorization: Basic YWRtaW46YWRtaW4= Content-Length: xx name=newcachebucket&ramQuotaMB=128&authType=none&proxyPort=11216&bucketType=memcached

Response

202: bucket will be created asynchronously with the location header returned.

No URI to check for the completion task is available, but most bucket creations complete within a few seconds.

Example

curl -d name=newcachebucket -d ramQuotaMB=128 -d authType=none -d proxyPort=11216 -d bucketType=memcached http://localhost:8080/pools/default/buckets

Creating a Membase Bucket

In addition to the aforementioned parameters, a replicaNumber parameter specifies the number of replicas.

Request

POST /pools/default/buckets HTTP/1.1 Host: node.in.your.cluster:8080 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 Example

202: bucket will be created.

curl -d name=newbucket -d ramQuotaMB=20 -d authType=none -d replicaNumber=2 -d proxyPort=11215 http://localhost:8080/pools/default/buckets

Getting a Bucket Request

GET /pools/default/buckets/Another bucket

Response

HTTP/1.1 200 OK Content-Type: application/com.membase.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" : 11311 } }, { "hostname" : "10.0.1.21", "uri" : "/addresses/10.0.1.21", "status" : "healthy", "ports" : { "routing" : 11211, "kvcache" : 11311 } } ] }

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

Modifying Bucket Properties

Buckets may be modified by POSTing the same kind of parameters used to create the bucket to the bucket's URI. Since an omitted parameter can be equivalent to not setting it in some cases, it is recommended that clients get existing parameters, make modifications where necessary, and then POST to the URI. The name of a bucket cannot be changed.

Increasing the Memory Quota for a Bucket

Increasing a bucket's ramQuotaMB from the current level. Note, the system will not let you decrease the ramQuotaMB for a membase bucket type and memcached bucket types will be flushed when the ramQuotaMB is changed.

Warning

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

Request (curl)

curl -d ramQuotaMB=25 -d authType=none -d proxyPort=11215 http://localhost:8080/pools/default/buckets/newbucket

Response

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

HTTP/1.1 202 OK Server: Membase 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 done with:

curl -d ramQuotaMB=130 -d authType=sasl -d saslPassword=letmein http://localhost:8080/pools/default/buckets/acache

Cluster and Pool Operations

Creating a new pool is not currently supported. A new pool may be supported in future releases. At that time a pool can be created by posting to the /pools URI.

Request

POST /pools/mynewpool name=mynewpool

Response

201: pool was created and valid URIs for referencing it returned 403: user not authorized (or no users are authorized because it is administratively disabled to all users)

Warning

For this release, this will always return 405 Method Not Allowed.

Joining a Cluster

Clusters (a.k.a. pools) cannot be merged if they are made of multiple nodes. However, a single node can be asked to join a cluster. It will need several parameters to be able to negotiate a join to the cluster.

Request

POST /node/controller/doJoinCluster Host: target.node.to.do.join.from: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

The following arguments are required:

Table 4.8. Cluster Joining Arguments

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 the server has been "secured" via the Membase Web Console, the following are also required

Table 4.9. Additional Arguments

Argument	Description
user	Administration user
password	Password associated with the Administration user

Response

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

Example (curl)

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

Ejecting a Node from a Cluster

In situations where a node is down either temporarily or permanently, we may need to eject it from the cluster. It may also be important to eject a node from another node participating in the same cluster.

Request

POST /controller/ejectNode Host: altnernate.node.in.cluster:8091 Authorization: Basic xxxxxxxxxxxx Accept: */* Content-Length: xxxxxxxxxx Content-Type: application/x-www-form-urlencoded otpNode=ns_1@192.168.0.1

Response

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

Example (curl)

curl -d otpNode=ns_1@192.168.0.107 http://192.168.0.106:8091/controller/ejectNode

System Logs

System modules log various messages, which are available via this interface. These log messages are optionally categorized by the module. Both a generic list of recent log entries and recent log entries for a particular category are available. A GET without specifying a category returns all categories.

Returned types may be "info" "crit" or "warn". Accessing logs requires administrator credentials if the system is secured.

Request

GET /pools/default/logs?cat=crit Host: node.in.your.pool.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/json X-memcachekv-Store-Client-Specification-Version: 0.1

Response

201: bucket was created and valid URIs returned HTTP/1.1 200 OK Content-Type: application/json Content-Length: nnn [{"cat":"info", "date": "", "code": "302", "message": "Some information for you."}, {"cat":"warn", "date": "", "code": "502", "message": "Something needs attention."}]

Client Logging Interface

Clients might want to add entries to the service's central logger. These entries would typically be responses to exceptional like difficulty handling a server response. For instance, the Web UI uses this functionality to log client error conditions for later diagnosis.

Request

POST /logClientError Host: node.in.your.pool.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/json X-memcachekv-Store-Client-Specification-Version: 0.1

Response

200 - OK