Conventions

These conventions apply across every endpoint. For the endpoint reference, use the API console built into CMP at /api-docs/v3/cmp/.

URLs and verbs

Paths follow a small number of patterns.

Both collections and items are called resources. Collections are the more common of the two.

Not every endpoint implements every verb. The API console lists the verbs each one accepts.

Object IDs

There are two kinds of IDs for addressing objects through the API. Every endpoint returns Global IDs, which are the recommended identifiers.

• Global ID (recommended). A prefix indicating the object type (such as BP for a blueprint), a dash, and eight characters drawn from lowercase letters and digits. For example, BP-a238b32r.
• Primary key ID. A number assigned in ascending order as objects are created. These do not persist across CMP instances.

Query string parameters

These parameters can be passed in the query string of any request. The first four shape what comes back; filter narrows which objects come back.

attributes

Appends to the list of attributes returned for the resource or collection. Takes a comma-delimited list.

For example:

/api/v3/cmp/users/?attributes=user.first-name,user.last-name,user.is-superuser

fields

Trims the response down to only the names you list. Takes a comma-delimited list and applies it to both attributes and _links entries. If none of the names is a link, _links is dropped from the response.

For example:

/api/v3/cmp/servers/?fields=hostname,status

links

Appends to the _links dictionary returned for the resource. Only links already defined by the endpoint can be requested; unrecognized names are ignored.

For example:

/api/v3/cmp/servers/?links=provision-job,actions

expands

Follows the named links and returns their full content inline, under an expanded_data key. Takes a comma-delimited list of link names.

For example:

/api/v3/cmp/servers/?expands=environment,owner

filter

Limits the resources returned in a collection. Takes a semicolon-delimited list of key-value pairs, each pair separated by a colon. Values are single strings or numbers, with booleans expressed as 0 or 1. Field names can traverse relationships with dots and take lookups such as .contains and .startswith.

For example:

• /api/v3/cmp/servers/?filter=hostname:linprodsvr0213
• /api/v3/cmp/servers/?filter=environment.name.contains:Dev
• /api/v3/cmp/users/?filter=user.first-name.startswith:A
• /api/v3/cmp/jobs/?filter=type:provision;status:success

Relationships and properties

Resources carry both:

• Relationships point to related resources. A server, for example, has an owner relationship pointing to a user.
• Properties are data attached to the resource that are not resources themselves, such as a server’s mem_size.

Response format

A successful request returns JSON, served as application/json, structured according to the Hypertext Application Language (HAL), a convention for expressing hyperlinks inside a JSON document. Responses carry a _links section, and collections also carry _embedded. See the HAL specification.

Because of that, a client can follow the relationships in _links instead of building URLs, and embed related resources with the expands parameter rather than requesting them separately.

Pagination

Collections are paginated.

A paginated response wraps the results in an envelope:

Rate limits

Requests are throttled per user at 10,000 requests per hour. A request that exceeds the limit is rejected with HTTP 429 and the standard error body described below.

Errors

The API uses standard HTTP status codes to signal success or failure. Every error response from /api/v3/ shares one pattern: a code matching the HTTP status, and an errors array. The array is always present, even when it holds a single error.

{
  "code": 400,
  "errors": [
    {
      "message": "Field 'name' may not be longer than 50 characters"
    }
  ]
}

Common status codes: