Getting started

This page contains background on how to start using the Crunchy Bridge API, and information on core concepts common to all endpoints. See also the API reference which is an exhaustive specification of each endpoint, its request/response structures, and examples of use.

New additions to the API and changes made to it are listed in the changelog.

Authentication

The API can be authenticated with using an API key retrieved from your account settings. Scroll to the "API Keys" section, and click Create API Key, which generates a secret for your use. This secret can then be used as a Bearer token in the Authorization header of other API requests:

curl -H "Authorization: Bearer cbkey_Z8b1Vob2vx7TbT8FqlgxUAqZruRBLJRMBJKB_thw4uY"
Copy

Export it as an environment variable to use other cURL API examples found on this site:

export CRUNCHY_API_KEY=cbkey_Z8b1Vob2vx7TbT8FqlgxUAqZruRBLJRMBJKB_thw4uY
Copy

You can also procure short-lived access tokens using an API key for an alternative authentication method that reduces the exposure of your long-lived API secret.

API compatibility

The Crunchy Bridge API aims to be as backwards compatible as possible, and will avoid changes which aren't considered backwards compatible:

• Removing an endpoint or changing its HTTP verb/URL.
• Adding a new required request parameter to an endpoint, or making a request parameter that was previously optional required.
• Removing a field on an endpoint response.
• Changing the type of a field in an endpoint response.

We don't commit to never making a backwards incompatible change, but will only so if it's important, and carefully. Any such changes will be announced beforehand and codified in the changelog.

HTTP verbs

The API tries to make appropriate use of HTTP verbs depending on the type of operation:

• GET: Used for read-only requests like listing and retrieval. Always idempotent.
• POST: Used for non-idempotent mutation endpoints like where when an API resource is created. Can be made idempotent with idempotency keys.
• PATCH: Used for endpoints where an API resource is being mutated non-idempotently. Can be made idempotent with idempotency keys.
• PUT: Used for endpoints where an API resource is being mutated idempotently. Generally, PUT endpoints can be used as upsert-style "create or update" actions. Always idempotent.
• DELETE: Used for endpoints where an API resource is being destroyed. Always idempotent.

Status codes

The API tries to make appropriate use of common HTTP status codes in responses. See the following matrix of status codes which are commonly returned and under what circumstances.

Precise status code compatibility isn't guaranteed, so best practice is to write clients to be tolerant of a variety of possible status codes. For example, don't write a client that requires a create action always return exactly a 201 — allow anything in the range of >= 200 and < 300 instead.

Some idempotent endpoints may use status code to hint at the action which occurred. For example when creating/updating a cluster logger, a 200 will indicate that an existing logger was updated while a 201 will indicate that one was freshly created.

Some endpoints may return a 410 instead of a 404 for a resource which wasn't found when it recognizes that although an ID doesn't exist anymore, it did exist previously. Clients trying to handle a case of a resource not found should respect either status code.

Errors

Error status codes give a broad hint as to the problem that may have occurred, but are often not specific enough to be helpful. The API will almost always provide a more detailed error message embedded in the response.

{
  "message": "Invalid credentials supplied for access to this resource.",
  "request_id": "5f805450-3565-4f34-8330-4ecb60d08bb9"
}
Copy

The error will also contain a request_id. In cases of an internal problem, it may be useful to provide this to support so that we can more easily locate the logs of the exact request which failed.

Pagination

List endpoints are paginated with cursor-based pagination. They'll return 100 items by default so it may not be necessary to integrate with it right away, but you may need to eventually, especially for larger collections. Paginated endpoints have these page-related parameters:

• cursor: A cursor at the beginning of the page to retrieve, usually procured by reading the value of the next_cursor field in a previous page. Left empty to get the first page.
• limit: The maximum number of items to return on the page. Defaults to 100 with a minimum of 1 and a maximum of 100.
• order: The order of pagination. asc for ascending or desc for descending. Defaults to asc.
• order_field: The name of the field on which to paginate. Supported fields are specific to each endpoint, and it’s not possible to specify any arbitrary name. See the documentation for each specific list endpoint to see which fields it supports. Defaults to id for most resources, and most only support id.

A typical paginated responses looks like this:

{
    "clusters": [
        ...
    ],
    "has_more": true,
    "next_cursor": "p56biajnfvgjhftvqs7lqymspe"
}
Copy

Pagination should follow these steps:

1. Fetch the first page by omitting the cursor parameter initially.
2. Consume all items on the current page. If has_more is true, pass the value of next_cursor as the cursor parameter to get the next page.
3. Repeat step (2) until has_more is false (and/or next_cursor is null, which is functionally the same).

Note that not all list endpoints support pagination. Make sure to look in the API reference at the specific endpoint you're trying to call to see if pagination parameters are present.

Rate limiting

Various actions in the API are rate limited to protect against client bugs, discourage abuse, and guarantee a stable platform for all users. The most common rate limit is number of allowed requests per second, but there may be others at play as well. Rate limited requests will get a 429 status code along with a more specific error message in the body (see errors) If the requests per second limit is hit, the API will respond with a Retry-After header containing the number of seconds the client should delay before trying again.

Rate limits are not guaranteed by API compatibility and may be subject to change. Well-behaved clients should be able to respect a returned 429 even if they encounter no rate limits today.

Request IDs

All API responses include an X-Request-Id header containing a UUID which uniquely fingerprints the request/response. Best practice is to log this value so that in case a problem is encountered, it can be provided to our support team who will then be able to easily identify the request in question.

Clients can also optionally generate their own request ID by sending X-Request-Id along with their request, which can be a better option in case of a problem where no response is received. Request IDs must be formatted as a valid UUID in common string format.

Unique identifiers

Almost all API resources will be uniquely identified by an id field in EID format. These IDs are stable, and unique across all accounts.