PingAM 7.5.1

REST API versions

REST API features are assigned version numbers.

Providing version numbers in the REST API helps ensure compatibility between releases. The version number of a feature increases when AM introduces a non-backwards-compatible change that affects clients making use of the feature.

AM provides versions for the following aspects of the REST API:

resource

Any changes to the structure or syntax of a returned response will incur a resource version change. For example, changing errorMessage to message in a JSON response.

protocol

Any changes to the methods used to make REST API calls will incur a protocol version change. For example, changing _action to $action in the required parameters of an API feature.

To ensure your clients are always compatible with a newer version of AM, you should always include resource versions in your REST calls.

Moreover, AM includes a CSRF filter for all the endpoints under /json that requires that all requests other than GET, HEAD, or OPTIONS include, at least, one of the following headers

  • X-Requested-With

  • Accept-API-Version

Learn more in Protect against CSRF attacks.

Specify REST API versions

You can specify which version of the REST API to use by adding an Accept-API-Version header to the request. The following example requests resource version 2.0 and protocol version 1.0:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
bash

You can configure the default behavior AM will take when a REST call doesn’t specify explicit version information. Learn more in Configure versioning behavior.

Supported REST API versions

Find information about the supported protocol and resource versions in the Online REST API reference available in the AM admin UI.

The Release notes describe any breaking changes between API versions.

Configure versioning behavior

Configure how AM handles REST calls that don’t present an API version:

  1. Log in as AM administrator, amAdmin.

  2. Click Configure > Global Services, and click REST APIs.

  3. In Default Version, select the required response to a REST API request that doesn’t specify an explicit version:

    The available options for default API version behavior are as follows:

    Latest

    The latest available supported version of the API is used.

    This is the preset default for new installations of AM.

    Oldest

    The oldest available supported version of the API is used.

    This is the preset default for upgraded AM instances.

    The oldest supported version might not be the first that was released, as API versions become deprecated or unsupported.

    Learn more in Deprecated in the Release notes.
    None

    No version will be used. When a client application calls a REST API without specifying the version, AM returns an error, and the request fails.

  4. Optionally, enable Warning Header to include warning messages in the headers of responses to requests.

  5. Save your work.

Version messages

AM provides REST API version messages in the JSON response to a REST API call. You can also configure AM to return version messages in the response headers.

Messages include:

  • Details of the REST API versions used to service a REST API call.

  • Warning messages if REST API version information is unspecified or is incorrect in a REST API call.

The resource and protocol version used to service a REST API call are returned in the Content-API-Version header, as shown below:

$ curl \
-i \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
HTTP/1.1 200 OK
Content-API-Version: protocol=1.0,resource=2.0
Server: Restlet-Framework/2.1.7
Content-Type: application/json;charset=UTF-8

{
    "tokenId":"AQIC5wM…​TU3OQ*",
    "successUrl":"/openam/console"
}
bash

If the default REST API version behavior is set to None, and a REST API call doesn’t include the Accept-API-Version header, or doesn’t specify a resource version, then a 404 Not Found status code is returned. For example:

$ curl \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0" \
https://openam.example.com:8443/openam/json/realms/root/serverinfo/*
{
  "code": 404,
  "reason": "Not Found",
  "message": "Resource '*' not found"
}
bash

If a REST API call does include the Accept-API-Version header, but the specified resource or protocol version doesn’t exist in AM, then a 404 Not Found status code is returned. For example:

$ curl \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0, resource=999.0" \
https://openam.example.com:8443/openam/json/realms/root/serverinfo/*
{
  "code": 404,
  "reason": "Not Found",
  "message": "Resource '*' not found"
}
bash

Find information on setting the default REST API version behavior in Specify REST API versions.