Using the Public API

  • beta
    +
    Get set up with an API Access token, and make your first REST interface call.
    The use of these Beta APIs in production applications is not supported.

    Thank you for trying out the Beta of our Couchbase Cloud Public API. For details of what’s involved in the trial see the introduction.

    If you’re ready to get started, the first thing that you will need is an API key.

    API Keys

    Couchbase Cloud Public API uses a Bearer token mechanism for authentication; each call to the Public API has to authenticate.

    To use the Bearer token mechanism with the Couchbase Cloud Public API, it is first necessary to obtain Access and Secret keys — this is done within Couchbase Cloud UI. These keys are specific to your account in Couchbase Cloud and also control authorization for API operations. For example, if you use Access and Secret keys with the Public API to create a cluster from a Couchbase Cloud account that itself cannot create a Cluster, then the API call will be refused.

    Access and Secret keys

    1. After logging into Couchbase Cloud, select API keys. You will see the list of API keys. Note: Only the access key is shown. The Secrets key is only seen during key creation. List of access keys in API keys management interface.

    2. Select Generate Key Generate key step.

    3. Enter a Key Name and select Submit. The keys will be generated and, after a short period of time, displayed. Key created - download this and take care to keep it safe.

      This is the only time the Secret key is shown. Make sure that you store it safely and securely. If, in the future, you misplace the key, you will need to generate a new one.
    4. Once you have stored the keys, select Close.

    Header values

    The header of each API call will need to contain the following:

    'Authorization': 'Bearer' + token
    'Couchbase-Timestamp' : 'now'
    
    Where
    token =  Access key + ':' + Base 64 encoded Hmac sha256 hash
    now = The number of milliseconds since 1970/01/01

    The Hmac sha256 hash uses the Secret Key with a message string made up from the following:

    • HTTP method being used e.g. GET

    • Endpoint being called e.g. /v2/clouds

    • The number of milliseconds since 1970/01/01

    • There needs to be a newline character after each one of these, but not the last one.

    Example complete message string
    GET\n/v2/clouds\n1614622252260

    To show how the Base 64 encoded Hmac sha256 hash is calculated, here’s an example using Python 3.

    cbc_api_endpoint = '/v2/clouds'
    cbc_api_method = 'GET'
    cbc_api_secret_key = ‘my secret key’
    
    # Epoch time in milliseconds
    cbc_api_now =  int(datetime.datetime.now().timestamp() * 1000)
    
    # Form the message string for the Hmac hash
    cbc_api_message= cbc_api_method + '\n' + cbc_api_endpoint + '\n' + str(cbc_api_now)
    
    # Calculate the hmac hash value with secret key and message
    cbc_api_signature'' = base64.b64encode(hmac.new(bytes(cbc_secret_key, 'utf-8'), bytes(cbc_api_message,'utf-8'), digestmod=hashlib.sha256).digest())
    
    # Values for the header
    cbc_api_request_headers = {
       'Authorization' : 'Bearer ' + cbc_access_key + ':' + cbc_api_signature.decode() ,
       'Couchbase-Timestamp' : str(cbc_api_now)
    }

    Revoking access

    Once Access and Secrets keys are being used to authenticate, they are valid until being revoked. To do this, login into Couchbase Cloud, select ‘API Keys’ and then choose the trash icon on the row of the Key that you want to revoke.

    1. Enter the API key name to confirm that it is the one you wish to remove and then select Confirm.

    2. The API key is now removed and any calls to the API, using those Access and Secret Keys, will now fail.

    Beta Test

    A Little Project for Those who Want to Get Involved

    We would like you to create a utility that can be used to provision clusters, manage them, and then destroy them when they are no longer needed. The same utility should be able to list summaries for clouds, projects, and clusters — and be able to obtain detailed information for each.

    The utility should be able to be used from the command line with parameters used for each of the operations. The utility will:

    • Provide a summary of the clouds, listing the name, ID, Provider and region.

    • Provide a detailed description of a cloud, showing all of the available information.

    • Provide a summary of the clusters, listing the name, ID, assigned project, cloud, and how many buckets there are.

    • Provide a detailed description of a cluster, showing all of the available information.

    • Provide a summary of all projects, listing the name and ID.

    • Create a cluster.

    • Add a user who can read / write to it.

    • Add an IP address to a cluster’s Allow List.

    • Delete a cluster.

    We would like you to implement as many of these features as possible in whatever programming language you are most comfortable with, taking advantage of the capabilities provided by the Public API.

    Example using Python v3

    This is a sample application to demonstrate using Couchbase Cloud Public API to automate operations. The application lists the cloud connections.

    Prerequisites

    The following pieces need to be in place in order to run the application:

    • Admission into the Restricted Beta.

    • Access and Secret Keys for authentication to the API.

    • Python 3.0 or greater.

    Running the application

    To download the application you can either download the archive or clone the repository:

    git clone https://github.com/couchbaselabs/cloud_public_api_sample
    Change directory
    cd cloud_public_api_sample

    The application uses several Python libraries that need to be installed. These are listed in requirements.txt and can be automatically loaded using the pip command:

    pip install -r requirements.txt

    Set environment variables for the base URL, and access and secret keys. Replace <> with your values for secret and access keys:

    export cbc_api_url='https://cloudapi.cloud.couchbase.com'
    export cbc_secret_key='<>'
    export cbc_access_key='<>'

    Launch the application by running the cloud_public_api_sample.py file from a terminal.

    python cloud_public_api_sample.py

    You will see a list of clouds in a table format, rather like this example

    Name Provider Region ID

    A Cloud

    aws

    us-east-2

    daeca03d-f6d8-4666-9b3e-3b913ec2da80