Cloudera API overview

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

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

Before you can use the Cloudera 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 Cloudera Management Console.

There are multiple ways to access the API:

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

Getting started with the Cloudera API

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

API access methods

Cloudera 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 Cloudera 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 Cloudera 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 Cloudera 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 Cloudera 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 Cloudera user account must have API access credentials (an API access key and private key) to access the Cloudera API through the CLI or other means. To use the CLI client, you configure the Cloudera 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 Cloudera Management Console documentation.

Request signing

cdpcurl, the Cloudera 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 Cloudera 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 Cloudera 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.

Cloudera API reference

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