Cloudera Docs

CDP API overview

CDP provides a REST API that enables you to access CDP functionality from a script, or to integrate CDP features with an application. In practice you can use the CDP API to script repetitive tasks, manage CDP resources, or even create custom applications.

The CDP API contains much of the functionality within the Management Console and Data Hub, as well as Cloudera Machine Learning, Data Warehouse, and Operational Database. For a complete CDP API reference, see the CDP Control Plane Public API Documentation.

Before you can use the CDP API, you must generate an API access key pair, which consists of an access key ID and a private key. You can generate the API access key through the Management Console.

There are multiple ways to access the API:

  • CDP CLI client
  • CDP SDK for Java
  • Directly, through a tool such as cdpcurl

Getting started with the CDP API

Getting started with the CDP API involves determining the best method for using the API, generating an API access key, and understanding permissions in the CDP API.

API access methods

CDP offers a CLI client, and all API commands have a CLI equivalent. See the CLI documentation for more details.

Java programmers might prefer to use the CDP SDK for Java. For more information, see the SDK documentation.

Alternatively, you can access API endpoints directly through your chosen HTTP client, such as curl. Cloudera offers cdpcurl, which is a Python command line tool that you can use to directly make CDP API calls, or embed in an application. cdpcurl returns JSON output for ease of use. It is based on awscurl and installation and usage are similar. Like the CDP CLI and SDK, cdpcurl has built-in CDP request signing to construct the headers required to make an API call. However, if you want to use a different HTTP client, such as curl, you can use a script within cdpcurl to generate the required headers.

You can also use the CDP API service definition files to create your own client-side code. The service definitions are in OpenAPI / Swagger 2.0 format and can be accessed here.

Generating an API access key

A CDP user account must have API access credentials (an API access key and private key) to access the CDP API through the CLI or other means. To use the CLI client, you configure the CDP client with the API access key and private key. To make API calls with cdpcurl, you pass the API access key and private key to cdpcurl.

Permissions

You are restricted to making API calls that are permissible based upon your user roles and resource roles. For more information on user roles, see the topic Understanding Roles and Resource Roles in the Management Console documentation.

Request signing

cdpcurl, the CDP SDK, and CDP CLI offer built-in request signing, but if you use a different HTTP client to make an API call, you must generate the required headers.

A CDP API call requires a request signature to be passed in the "x-altus-auth" header, along with a corresponding timestamp in the "x-altus-date" header. cdpcurl constructs the headers automatically. However, if you would rather use a different HTTP client, such as ordinary curl, you can use the cdpv1sign script within cdpcurl to generate these required headers.

You can then parse the header values from the script output and feed them to your preferred client. Note that CDP API services will reject calls with timestamps too far in the past, so generate new headers for each call.

For example:

$ cdpv1sign -X POST https://api.us-west-1.cdp.cloudera.com/api/v1/environments2/listEnvironments
Content-Type: application/json
x-altus-date: Fri, 28 Aug 2020 20:38:38 GMT
x-altus-auth: (long string value)

The request signing specification is available here.

CDP API reference

The CDP API reference documentation is available here. Use this documentation to find the desired API endpoint, request parameters, and responses.