Skip to main content

API Conventions

Most Management API endpoints follow a common set of conventions. This page covers the ones that apply broadly, so the other pages in this section don't need to repeat them. Filtering has its own dedicated page — see Filtering.

Request and response format​

Requests and responses use JSON. Send Content-Type: application/json on requests with a body, and Accept: application/json to make sure you get a JSON error response if something goes wrong instead of a default HTML one.

Pagination​

List endpoints accept startIndex and count query parameters:

  • startIndex — 0-based index of the first result to return, skipping this many items from the full result set.
  • count — maximum number of items to return. Most endpoints cap this at 500 regardless of what you request.
GET /api/rest/v1/user?startIndex=50&count=25

A paginated response is wrapped in an object with the page of results and enough information to fetch the next one:

{
    "totalResults": 1204,
    "startIndex": 50,
    "itemsPerPage": 25,
    "resources": [
        { "...": "one resource per item in this page" }
    ]
}

totalResults is the total number of matching items across all pages, ignoring pagination — use it to know when you've paged through everything. Not every list endpoint supports pagination; a few (for example listing namespaces) always return every accessible result at once.

Sorting​

Many of the same list endpoints also accept sortBy and sortOrder:

  • sortBy — the attribute name to sort by, for example name or createdDate.
  • sortOrder — ascending or descending.
GET /api/rest/v1/user?sortBy=username&sortOrder=ascending

Without sortBy, results are returned in natural order — usually creation order. Sorting a large result set can be noticeably slower than an unsorted query, since it can't always be satisfied by an existing database index.

Error responses​

An error response body looks like:

{
    "statusCode": 400,
    "errorCode": "filter-parsing-error",
    "errorMessage": "Human readable error description",
    "errorList": [
        { "errorCode": "...", "errorMessage": "..." }
    ]
}

statusCode repeats the HTTP status code. errorCode is a short, stable, machine-readable identifier you can safely match against in code; errorMessage is a human-readable description that may change between versions — don't parse it. errorList is only present for errors that break down into several individual problems (for example, several invalid fields in one request) and is otherwise omitted.

Request logging header​

Any request can include an X-Log-Message header with a short, free-form string. It's attached to the event log entries the request causes, which is useful for correlating a specific API call with what shows up in the Event Log afterward.

X-Log-Message: Bulk import batch #42
Last updated on