You are viewing the documentation for a prerelease version.

View Latest

Collections via REST

Collections can be managed by means of the Couchbase REST API.

Using the REST API

The following sequence of REST API commands demonstrates how to create, examine, and delete scopes and collections. It assumes that Couchbase Server has been installed, initialized, and provisioned on a Ubuntu system. Note, however, that the sequence should work identically on other Linux systems; as well as on MacOS and Windows systems.

At the command-line prompt, proceed as follows:

  1. Create a bucket, named testBucket, using the /pools/default/buckets REST method:

    curl -X POST -u Administrator:password \
    http://localhost:8091/pools/default/buckets \
    -d name=testBucket \
    -d ramQuotaMB=100

    For information on this REST call and its parameters, see Creating and Editing Buckets.

  2. Create a scope. This is a POST operation, using the /pools/default/buckets/<bucket>/collections endpoint, and specifying the -name parameter.

    curl -u Administrator:password -X POST \
    http://localhost:8091/pools/default/buckets/testBucket/collections \
    -d name=my_scope

    If successful, the command returns a uid for the action (this is principally for internal use, and need not be tracked by the user):

    {"uid":1}

    Now, examine the collections manifest for the specified bucket. This is a GET operation, using the same endpoint as the previous POST, with no parameter.

    curl -u Administrator:password -X GET \
    http://localhost:8091/pools/default/buckets/testBucket/collections

    This returns the following output:

    {"my_scope":{},"_default":{"_default":{}}}

    Formatted, this output is as follows:

    {
      "my_scope": {},
      "_default": {
        "_default": {}
      }
    }

    This output shows that the bucket now contains two scopes, which are my_scope and _default. The _default scope contains a single collection, which is also named _default.

  3. Create two collections, within the created scope. This requires a POST operation, specifying the created scope as endpoint, and using the -name parameter to specify the new collection-name. For the first collection, enter the following command:

    curl -u Administrator:password -X POST \
    http://localhost:8091/pools/default/buckets/testBucket/collections/my_scope \
    -d name=my_collection_in_my_scope_1

    If successful, the operation returns a uid.

    {"uid":2}

    Create the second collection as follows:

    curl -u Administrator:password -X POST \
    http://localhost:8091/pools/default/buckets/testBucket/collections/my_scope \
    -d name=my_collection_in_my_scope_2

    Again, success returns a uid:

    {"uid":3}

    Now, re-examine the collections manifest for the bucket.

    curl -u Administrator:password -X GET \
    http://localhost:8091/pools/default/buckets/testBucket/collections

    The unformatted output is as follows:

    {"my_scope":{"my_collection_in_my_scope_2":{},"my_collection_in_my_scope_1":{}},"_default":{"_default":{}}}

    When formatted, the output takes the following appearance:

    {
      "my_scope": {
        "my_collection_in_my_scope_2": {},
        "my_collection_in_my_scope_1": {}
      },
      "_default": {
        "_default": {}
      }
    }

    This indicates that the collections my_collection_in_my_scope_1 and my_collection_in_my_scope_2 have been successfully created in my_scope.

  4. Create a collection in the default scope. This is a POST operation, specifying the _default scope as endpoint, and the -name parameter to specify the new collection-name.

    curl -u Administrator:password -X POST \
    http://localhost:8091/pools/default/buckets/testBucket/collections/_default \
    -d name=my_collection_in_default_scope

    A uid is returned:

    {"uid":4}

    Now, re-examine the collections manifest for the bucket.

    curl -u Administrator:password -X GET \
    http://localhost:8091/pools/default/buckets/testBucket/collections

    When formatted the output is as follows:

    {
      "my_scope": {
        "my_collection_in_my_scope_2": {},
        "my_collection_in_my_scope_1": {}
      },
      "_default": {
        "my_collection_in_default_scope": {},
        "_default": {}
      }
    }

    This indicates that the collection my_collection_in_default_scope has been successfully created in the _default scope, and so appears alongside the _default collection.

  5. Drop a collection from the created scope. This requires a DELETE operation, and the endpoint that specifies the collection that is to be dropped.

    curl -u Administrator:password -X DELETE \
    http://localhost:8091/pools/default/buckets/testBucket/collections/\
    my_scope/my_collection_in_my_scope_1

    This returns a uid:

    {"uid":5}

    Now, re-examine the collections manifest for the bucket.

    curl -u Administrator:password -X GET \
    http://localhost:8091/pools/default/buckets/testBucket/collections

    The output (here formatted) indicates that the collection my_collection_in_my_scope_1 has successfully been dropped from my_scope:

    {
      "my_scope": {
        "my_collection_in_my_scope_2": {}
      },
      "_default": {
        "my_collection_in_default_scope": {},
        "_default": {}
      }
    }
  6. Drop a collection from the created scope. This requires a DELETE operation, and the endpoint that specifies the collection that is to be dropped.

    curl -u Administrator:password -X DELETE \
    http://localhost:8091/pools/default/buckets/testBucket/collections/\
    my_scope/my_collection_in_my_scope_1

    This returns a uid:

    {"uid":5}

    Now, re-examine the collections manifest for the bucket.

    curl -u Administrator:password -X GET \
    http://localhost:8091/pools/default/buckets/testBucket/collections

    The output (here formatted) indicates that the collection my_collection_in_my_scope_1 has successfully been dropped from my_scope:

    {
      "my_scope": {
        "my_collection_in_my_scope_2": {}
      },
      "_default": {
        "my_collection_in_default_scope": {},
        "_default": {}
      }
    }
  7. Drop the created scope, and examine the manifest.

    curl -u Administrator:password -X DELETE \
    http://localhost:8091/pools/default/buckets/testBucket/collections/my_scope

    This returns a uid:

    {"uid":6}

    Examine the manifest:

    curl -u Administrator:password -X GET \
    http://localhost:8091/pools/default/buckets/testBucket/collections

    The output (here formatted), the output is as follows:

    {
      "_default": {
        "my_collection_in_default_scope": {},
        "_default": {}
      }
    }

    This indicates that my_scope has successfully been dropped; and with it, the collection my_collection_in_my_scope_2.

This concludes the sequence of commands.

A reference page for each of the available REST methods is provided in REST API Reference.