Introduction

This document describes the Cloudera Manager REST API. All requests and responses are presented in Javascript Object Notation (JSON).

The API resources listed below follow standard Create-Read-Update-Delete (CRUD) semantics where the HTTP request path defines the entity to be acted on and the HTTP method expresses the type of action to perform.

HTTP Method	Operation
POST	Create entries
GET	Read entries
PUT	Update or edit entries
DELETE	Delete entries

All collections in the API use plural names, 'users', instead of the singular, 'user'. To address a specific user in the system, expand the URL path to include the user identifier. For example, '/users/foo' identifies user 'foo' and '/users/bar' identifies user 'bar'.

Collection	POST (create)	GET (read)	PUT (update)	DELETE (delete)
/users	Create a new user	List all users in the system	Bulk update all users	Delete all users
/users/foo	error	Read information about user 'foo'	If user 'foo' exists, update their information; otherwise, error.	Delete user 'foo'

Keep in mind that not all collections supports all operations. For example, events in the system are read-only; you cannot create new events with the API.

You can list the entries in a collection using one of two views: 'summary' or 'full'. The default 'summary' view provides the core information about each entry. The 'full' view is more heavyweight and provides a fully expanded view of each entry. The view is controlled by a query parameter called 'view' e.g. 'GET /users?view=full'.

HTTP requests should set the "Content-Type" header to "application/json" for most calls, unless specified otherwise.

Authentication

The Cloudera Manager API uses HTTP basic access authentication. It accepts the same user credentials as the web interface. Different users may have different level of access, as defined by their roles. (See the user management API calls for more.) With every authenticated request, the server returns a session cookie, which can be subsequently used for authentication.

Error Code

The API returns HTTP code in the 400s and 500s upon errors:

400 — Invalid request parameters; Malformed requests
401 — Authentication failure
403 — Authorization failure
404 — Object not found
500 — Internal API error
503 — Response temporarily unavailable; caller should retry later

See /tools/echoError for a discussion on the body of an error response.

API Usage Tutorial

Tutorial link.

API Version

The API can be queried for the latest version it supports. By making a GET request to the '/version' URL, a string will be returned with the highest supported version (for example, "v2").

Note that servers that only support API v1 do not support this call. In that case, a 404 error will be returned, and can be used to detect that the server only supports v1.

The version should be prepended to the path of the REST resources listed below. The documentation of the different resources lists the version which added the particular functionality.

REST Resources

This API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. The following resources are accessible through the RESTful model:

There is also a WADL document describing the REST API.

Data Model

All endpoints act on a common set of data. The Cloudera Manager API uses JSON.