Cloudera Manager API Migration Notes

This document outlines the transition of the Cloudera Manager REST API from Swagger 2 to OpenAPI 3.0 starting with Cloudera Manager version 7.13.2.0. It details necessary code changes for Java and Python clients, including data type shifts and authentication changes, ensuring your integrations remain compatible while leveraging the improved performance and strict typing of the new specification.

Overview and Compatibility

The Cloudera Manager server traditionally provides its public REST API through Swagger 2 specifications.

Starting with Cloudera Manager 7.13.2.0, the REST API moves to the OpenAPI 3.0 specification because Java 8 is no longer supported. The OpenAPI specification introduces differences that require changes in the updated REST API implementation.

Client Compatibility: Older API clients continue to work with the Cloudera Manager 7.13.2.0 server. You only need to migrate your code if you require access to new endpoints introduced in Cloudera Manager 7.13.2.0.
Python Support: This version officially removes support for Python 2.x.
Data Type Changes: A key change in OpenAPI 3.0 is the removal of the file type. Because code generators require this type to create client code, this change affects all API endpoints that currently reference file.

Cloudera offers pre-built client bindings in Java and Python for the REST API. Use the following steps to migrate your code to the new API clients.

Java Client Updates

Numerical Data Type Shift: BigDecimal to Long

In the previous client, many method signatures use the BigDecimal type for numerical arguments. Because OpenAPI 3.0 specifications require precise type definitions, the current client uses Long in place of BigDecimal.

AuditsResourceApi Change: Stream Audits

The AuditsResourceApi.streamAudits method now returns a String instead of a File. This change follows OpenAPI 3.0 compliance rules and might impact performance.

Previous Signature:

java.io.File streamAudits(String endTime, BigDecimal maxResults, String query, BigDecimal resultOffset, String startTime)

Current Signature:

String streamAudits(String endTime, BigDecimal maxResults, String query, BigDecimal resultOffset, String startTime)

Example 1: Use the new type directly.

AuditsResourceApi auditsApi = new AuditsResourceApi();
String auditsJson = auditsApi.streamAudits("now", BigDecimal.valueOf(100), null,
    BigDecimal.valueOf(0), null);
// deserialize auditsJson ...

Example 2: Save to File like the previous client.

AuditsResourceApi auditsApi = new AuditsResourceApi();
Response response = auditsApi
    .streamAuditsCall("now", BigDecimal.valueOf(100), null,
        BigDecimal.valueOf(0), null, null, null)
    .execute();
File file = Configuration.getDefaultApiClient().downloadFileFromResponse(response);

ControlPlanesResourceApi Change: Get Manifest JSON

The ControlPlanesResourceApi.getManifestJson method now returns a String instead of a File. This update follows OpenAPI 3.0 compliance rules.

Previous Signature:

java.io.File getManifestJson(ApiRemoteRepoUrl remoteRepoUrl)

Current Signature:

String getManifestJson(ApiRemoteRepoUrl remoteRepoUrl)

Example: Save to File

Follow the streamAudits example to save the response data to a file. Use the getManifestJsonCall method to execute the call and download the file from the response.

ControlPlanesResourceApi Change: Get Log Content

The ControlPlanesResourceApi.getLogContent method now returns a String and accepts a Long type for the command ID. This update follows OpenAPI 3.0 compliance rules.

Previous Signature:

java.io.File getLogContent(java.math.BigDecimal commandId)

Current Signature:

String getLogContent(Long commandId)

Example: Save to File

Use the getLogContentCall method to execute the call and save the response data to a file.

ControlPlanesResourceApi controlPlanesApi = new ControlPlanesResourceApi();
Response response = controlPlanesApi
    .getLogContentCall(123L, null, null)
    .execute();
File file = Configuration.getDefaultApiClient().downloadFileFromResponse(response);

Python Client Updates

Python Client Setup and Configuration

The current client code no longer accepts a URL as an argument for the cm_client.ApiClient constructor. You must use a Configuration object to set the host and configure Basic Authentication.

Follow these steps to configure the connection and use Basic Authentication for all subsequent requests.

Example: Configure the Connection

configuration = cm_client.Configuration()
configuration.host = 'https://cm_server_host:7183/api/v58'
configuration.username = 'admin'
configuration.password = 'admin'

# Encode and set Basic Auth header
auth_str = base64.b64encode(f"{configuration.username}:{configuration.password}".encode()).decode("utf-8")
api_client = cm_client.ApiClient(configuration)
api_client.default_headers["Authorization"] = f"Basic {auth_str}"

Python ApiException Import Change

Previous Python clients import ApiException within ApiClient automatically. The current client no longer performs this import. To fix this, update your code with one of the following options:

Option 1: Add a Direct Import

Add this line to your code: import cm_client.rest.ApiException

Option 2: Use the rest Namespace

If your code already imports cm_client, update all ApiException references to: rest.ApiException

Persistent File Support for Legacy APIs

Cloudera simplified the transition for APIs that previously returned a 'file', meaning you do not need to make any changes.

The new compatibility layer automatically handles file returns so your current code continues to work without any manual updates.

To prevent widespread breaks for users following the removal of file from OpenAPI, Cloudera built a code layer. This layer allows you to use client APIs exactly as you did in the past. For specific APIs, a transparent adapter handles the task of reading response data and writing it to a file.

This ensures the caller avoids any modifications. The logic within this adapter replicates the exact process found in the previous client code.

Persistent Text Support for Legacy APIs

Cloudera provides a new internal adapter that automatically processes UTF-8 text responses to ensure current code remains compatible without any manual updates.

For the Simplified API Transition, you do not need to make any changes to APIs that provide text content.

Cloudera maintains several API endpoints that return a ‘text/plain’ content type. During a call, the previous client performs a UTF-8 decode automatically. New clients show an issue; they return a string literal with the representation of the bytes.

To bypass this, a user must call the API with _preload_content=False and process the response manually, or add a line to evaluate the string and then call decode. Cloudera now uses an adapter to maintain compatibility for these APIs. This adapter performs the evaluation and UTF-8 decoding automatically.