Make an API Call with the Management API v3.0

  • Capella Operational
  • how-to
    +
    How to make an API call with the Management API v3.0, formerly known as the Public API.
    Deprecation Notice

    The Management API v3.0 is deprecated and will be removed in future. Users of the Management API v3.0 must plan to migrate to the Management API v4.0. See Manage Deployments with the Management API v4.0.

    Prerequisites

    In order make an API call with the Management API v3.0, you must have an API key that was created for the Management API v3.0. API keys for the Management API v4.0 are not compatible with the Management API v3.0.

    To create an API key for the Management API v3.0, see Get Started with the Management API v3.0.

    HTTP Headers

    Each API call must contain the following headers:

    Authorization: Bearer <token>
    Couchbase-Timestamp: <now>

    Where:

    <token>

    is made up of the API access key, followed by a colon :, followed by a Base64-encoded HMAC SHA-256 hash.

    <now>

    is the number of milliseconds since 1970/01/01.

    Base64-Encoded HMAC SHA-256 Hash

    You must calculate the Base64-encoded HMAC SHA-256 hash from the API secret key and a message string. The message string is made up of the following:

    • The HTTP method being used, such as GET.

    • The endpoint being called, such as /v2/clouds.

    • The number of milliseconds since 1970/01/01.

    There must be a newline character after each one of these, except the last. How the newline character is represented depends on the language used. In the following example, the newline character is escaped as \n:

    GET\n/v2/clouds\n1614622252260

    Make an API Call

    You can use a client such as cURL or a native SDK call to make an API call with the Management API v3.0.

    To make an API call:

    1. Use the following base URL.

    2. Pass the HTTP Authorization and Couchbase-Timestamp headers.

    3. If a request body is required, pass it in JSON format.

    Alternatively, you can use a client such as Insomnia or Postman to explore the details of the REST API, generate code samples, and so on. The Management API v3.0 uses an OpenAPI v3 specification. To download the Management API v3.0 specification, go to the Management API Reference and find the link to the openapi.yaml file.

    Examples

    Calculate the HMAC SHA-256 Hash

    To show how the Base64-encoded HMAC SHA-256 hash is calculated, here’s an example using Python 3.

    • <api-access-key> is the API access key.

    • <api-secret-key> is the API secret key.

    import base64
    import datetime
    import hashlib
    import hmac
    
    cbc_api_endpoint = '/v3/clusters'
    cbc_api_method = 'GET'
    cbc_secret_key = '<api-secret-key>'
    cbc_access_key = '<api-access-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)
    }
    
    print (cbc_api_request_headers)

    List Clusters

    The following Bash script lists all clusters available to the provided API key.

    • <api-access-key> is the API access key.

    • <api-secret-key> is the API secret key.

    #!/bin/bash
    
    ACCESS=<api-access-key>
    SECRET=<api-secret-key>
    BASEURL=https://cloudapi.cloud.couchbase.com
    
    METHOD=GET
    ENDPOINT=/v3/clusters
    NOW=`date +%s000`
    
    MESSAGE="$METHOD
    $ENDPOINT
    $NOW"
    
    HASH=`echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64`
    
    curl -X $METHOD "$BASEURL$ENDPOINT" \
      -H "Authorization: Bearer $ACCESS:$HASH" \
      -H "Couchbase-Timestamp: $NOW"

    The response is a JSON object similar to the following.

    Result
    {
      "cursor": {
        "pages": {
          "page": 1,
          "next": 2,
          "last": 6,
          "perPage": 10,
          "totalItems": 58
        },
        "hrefs": {
          "first": "http://<BASEURL>/public/v3/clusters?page=1&perPage=10",
          "last": "http://<BASEURL>/public/v3/clusters?page=6&perPage=10",
          "next": "http://<BASEURL>/public/v3/clusters?page=2&perPage=10"
        }
      },
      "data": {
        "items": [
          {
            "environment": "hosted",
            "id": "<redacted>",
            "name": "a1-saicharan-loyaladalovelace",
            "projectId": "<redacted>"
          },
    // ...
          {
            "environment": "hosted",
            "id": "<redacted>",
            "name": "bravewilliamwulf",
            "projectId": "<redacted>"
          }
        ],
        "tenantId": "<redacted>"
      }
    }

    Note that this response contains cursor information, showing the pagination of the results.

    Next Steps