The mapping between the vBucket designation and the client interface operates through a request to the Couchbase Server via client-initiated REST/JSON requests. The REST/JSON URLs should be provided to the client library as some initial configuration parameter by the user's application. The client application should bootstrap the REST/JSON information by "chasing URLs" from a standard base, starting URL.

Eventually, after following the bootstrapping sequence, your client library will have a REST/JSON URL that looks like:

http://HOST:PORT/pools/default/bucketsStreaming/BUCKET_NAME

For example:

http://couchbase1:8091/pools/default/bucketsStreaming/default

Here's an example response when requesting that URL, in JSON:

{
    "name" : "default",
    "bucketType" : "couchbase",
...
    "vBucketServerMap" : {
        "hashAlgorithm" : "CRC",
        "numReplicas" : 1,
        "serverList" : ["10.1.2.14:11210"],
        "vBucketMap" : [[0,-1],[0,-1],[0,-1],[0,-1],[0,-1] : ]
   }
}

The REST/JSON URLs might be under HTTP Basic Auth authentication control, so the client application may also have to provide (optional) user/password information to the your client library so that the proper HTTP/REST request can be made.

The REST/JSON URLs are "streaming", in that the couchbase REST server doesn't close the HTTP REST connection after responding with one vBucket-to-server map. Instead, couchbase keeps the connection open, and continues to stream new maps to your client library when there are cluster changes (new server nodes being added, removed, and/or vBuckets getting reassigned to different servers). In the couchbase streaming approach, new vBucket-to-server map JSON messages are delimited by 4 newlines ("\n\n\n\n") characters.

The above section describes what we call "per-bucket" REST/JSON URLs. That is, each port-based bucket has a streaming REST/JSON URL of the form:

http://HOST:PORT/pools/default/bucketsStreaming/BUCKET_NAME

There is another kind of REST/JSON URL, which describes all SASL-authenticated buckets. This SASL REST/JSON URL has the form of:

http://HOST:PORT/pools/default/saslBucketsStreaming

Sample output:

{"buckets":[
    {"name":"default",
            "nodeLocator":"vbucket",
            "saslPassword":"",
            "nodes":[
             {"clusterMembership":"active","status":"healthy","hostname":"10.1.4.11:8091",
             "version":"1.6.1rc1","os":"x86_64-unknown-linux-gnu",
             "ports":{"proxy":11211,"direct":11210}},
             {"clusterMembership":"active","status":"healthy","hostname":"10.1.4.12:8091",
             "version":"1.6.1pre_21_g5aa2027","os":"x86_64-unknown-linux-gnu",
             "ports":{"proxy":11211,"direct":11210}}],
            "vBucketServerMap":{
            "hashAlgorithm":"CRC","numReplicas":1,
        "serverList":["10.1.4.11:11210","10.1.4.12:11210"],
        "vBucketMap":[[0,-1],[1,-1],...,[0,-1],[0,-1]]}}

 ]
        }

One main difference between the SASL REST/JSON response versus the per-bucket REST/JSON response is that the SASL REST/JSON response can describe more than one bucket. In the SASL REST/JSON response, these multiple buckets would be found under the "buckets" array.