Skip to main content

Overview

The CelerData Cloud BYOC API is an HTTPS-based RESTful interface that provides you with programmatic access to manage administrative objects within CelerData Cloud. With this API, you can securely create, manage, and query various resources such as clusters, warehouses (available only to elastic clusters), usage, and billing.

This API has the following features:

  • JSON entities. All entities are expressed in JSON.
  • HTTPS-only. You can access the API only via HTTPS. This ensures that all the data sent over the network is encrypted with TLS.
  • Client Credentials-based authentication in compliance with OAuth 2.0. Before you access the API, you must generate an application key or create a service account, convert its client ID and secret key into a base64 encoded string, and then use the string to create an access token, which grants you authorization to the API.

This guide introduces what you need to do before using the API and walks you through the process of making an API call.

Before you begin​

To complete this guide, you need to:

Obtain access token​

Step 1: Generate Client ID and Client secret​

Currently, CelerData Cloud BYOC supports authentication with application keys and service accounts.

You can choose either to generate an application key or create a service account to acquire the Client ID and Client secret.

Generate an application key​

  1. Sign in to the CelerData Cloud BYOC console.

  2. In the left-side navigation pane, choose Application keys.

  3. On the Application keys page, click New secret.

  4. In the dialog box that appears, optionally enter a description, and then click Generate now to generate an application key. Then, copy the Secret and Client ID before you close the dialog box.

    NOTE

    The Secret can be viewed only when the application key is created. Make sure that you copy and save the Secret before closing the dialog box.

    Create an application key

For more information about managing application keys, see Application keys.

Create a service account​

  1. Sign in to the CelerData Cloud BYOC console.

  2. In the left-side navigation pane, choose Access Control > Member.

  3. On the Members page, click the Service accounts tab.

  4. On the Service accounts tab, click Create a service account.

  5. In the Generate secret for service account dialog box, enter a name for the service account, and click Generate now.

  6. Copy the Client Secret and Client ID, and click Yes, I have finished it to close the dialog box.

    NOTE

    The Client Secret can be viewed only when the service account is created. Make sure that you copy and save the Client Secret before closing the dialog box.

  7. On the detail page of the service account, click the Granted roles tab.

  8. On the Granted roles tab, select the role you want to assign from the Assign new role drop-down list, and click Assign.

For more information about managing service accounts, see Service accounts.

Step 2: Generate a base64 encoded string​

Use the following command to generate a base64 encoded string:

echo -n <client_id>:<secret> | base64 | tr -d "\n"

Note that you must replace <client_id> and <secret> in the preceding command with the client ID and secret key you obtained in the above Step 1. Example:

echo -n 50292c3c-2b95-417f-880d-0c7e8c26eac1:YOklxY24RKgveikknUI48RuHnkPsFit1u0i2TGyp | base64 | tr -d "\n"

A base64 encoded string like below is returned:

NTAyOTJjM2MtMmI5NS00MTdmLTg4MGQtMGM3ZThjMjZlYWMxOllPa2x4WTI0UktndmVpa2tuVUk0OFJ1SG5rUHNGaXQxdTBpMlRHeXA=

The generated base64 encoded string can then be used to make the API call for creating an access token, in which case it is added as an Authorization: Basic base64(<client_id>:<secret>) header to the HTTP request.

Step 3: Create an access token​

Make an API call to create an access token. You must add the base64 encoded <client_id>:<secret> string generated in the above Step 2 as an Authorization: Basic base64(<client_id>:<secret>) header to the HTTP request. For details, see Create access token.

The access token created can then be used to make other API calls in which it is added as an Authorization: Bearer <access_token> header to the HTTP requests.

(Optional) Obtain cluster ID​

For some API calls, you will need to provide the ID of the CelerData cluster you want to query. Follow these steps to obtain the cluster ID:

  1. Sign in to the CelerData Cloud BYOC console.
  2. In the left-side navigation pane, choose Clusters.
  3. On the page that appears, click the cluster you want to query.
  4. On the Overview tab of the cluster details page, navigate to the Cluster properties section, where you can find the Cluster ID.

Make an API call​

This section uses curl as an example to describe how to query the CCU usage of a cluster, helping you understand how you can build an API call and check the response.

Build an API call​

Suppose that the cluster ID is 82964bc5-a8ce-4236-9fe6-1ad1e0f80e15 and the access token is NWM0MWU1NJGTZME1OC0ZZDNKLTK0MZKTODQXM2EXNGM3MTYX.

Run the following command in your terminal to query the CCU usage of the cluster within the time range of June 1, 2023 to June 31, 2023 and view the CCU usage details on a daily basis:

    curl --request GET \
  --url 'https://cloud-api.celerdata.com/api/1.0/usages/82964bc5-a8ce-4236-9fe6-1ad1e0f80e15?start_date=20230701&end_date=20230731&show_detail=true' \
  --header 'Authorization: Bearer NWM0MWU1NJGTZME1OC0ZZDNKLTK0MZKTODQXM2EXNGM3MTYX'

Check the response​

After you submit the API call, if the status code in the response is 20000 and you see details about the usage of the cluster, your request is successful.

The response body consists of three parts:

  • code: the error code. If the error code returned is 20000, the request succeeded. If any other error code is returned, the request failed.
  • data: the result of the API call. The data object may not be returned for some API actions.
  • message: the error message. This field is returned only when the code returned is not 20000. Do not conclude whether a request succeeded or failed based on the return value of message.

Here is an example of the response to a successful API call:

{
    "code":20000,
    "data":{
        "cluster_id":"82964bc5-a8ce-4236-9fe6-1ad1e0f80e15",
        "cluster_name":"test_privilege_30-wybing",
        "total_usage":"87.025277",
        "details":[
            {
                "usage":"18.130654",
                "date":20230703
            }
        ]
    }
}