# Conventions

> How the Cloud Management Platform (CMP) REST API is shaped: its URLs, identifiers, query parameters, responses, limits, and errors

---

Site [llms.txt](/llms.txt)

---

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.

| Path | What it addresses |
| --- | --- |
| `/{plural-noun}` | A collection of that type, such as `/api/v3/cmp/servers/`. |
| `/{plural-noun}/{id}` | A single item within a collection. |
| `/{single-noun}` | A singleton that exists without a collection. The current-user singleton is `/api/v3/cmp/user/`. |
| `/{plural-noun}/actions/{action}` | Functionality better expressed in RPC style than REST, such as `/resource-handlers/actions/sync-vms`. |

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

| Verb | On a collection | On an item |
| --- | --- | --- |
| `GET` | List the items. | Retrieve the item. |
| `POST` | Create an item. On an `actions` path, trigger the action. | |
| `PUT` | | Replace the item. |
| `PATCH` | | Update part of the item. |
| `DELETE` | | Delete the item. |

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`

<div class="alert alert-info" role="alert">


Each expansion is a separate lookup, so expanding several links across a large results page costs more than fetching the page.
</div>


### 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](http://tools.ietf.org/html/draft-kelly-json-hal-06).

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.

| Parameter | What it does |
| --- | --- |
| `page` | The page to return. |
| `page_size` | Items per page. The default is **10**; the maximum is **10,000**. |

A paginated response wraps the results in an envelope:

| Key | Contents |
| --- | --- |
| `_links` | Navigation links for the collection: self, previous, and next. |
| `total` | The number of objects across all pages. |
| `count` | The number of objects on this page. |
| `_embedded` | The objects themselves, under a key named for the collection in the request path. A request to `/api/v3/cmp/servers/` returns them under `servers`; a request to `/api/v3/cmp/resourceHandlers/vmware/` returns them under `vmware`. |

<div class="alert alert-info" role="alert">


Collections are not returned in a guaranteed order. Sort in your client, or filter for the objects you need.
</div>


## 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.

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

Common status codes:

| Status | Meaning |
| --- | --- |
| `401` | Authentication failed. The token is missing, malformed, or expired. See [Authentication](/docs/cmp/developer-resources/rest-api/authentication/). |
| `403` | Authenticated, but not permitted. See [Access policy](/docs/cmp/developer-resources/rest-api/#access-policy). |
| `429` | The rate limit has been exceeded. |

<div class="alert alert-info" role="alert">


Error responses carry a sanitized message. The full exception, including its traceback, is written to the CMP application log.
</div>