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

For more information about the filter, see 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'

You can configure the default behavior AM will take when a REST call does not specify explicit version information. For more information, refer to Configure versioning behavior.

Supported REST API versions

For information about the supported protocol and resource versions available in AM, see 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 behaves to REST calls that are not presenting API versions:

  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 does not 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 may not be the first that was released, as APIs versions become deprecated or unsupported.

    For details, refer to 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"
}

If the default REST API version behavior is set to None, and a REST API call does not include the Accept-API-Version header, or does not specify a resource version, then a 400 Bad Request status code is returned, as shown below:

$ curl \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0" \
https://openam.example.com:8443/openam/json/realms/root/serverinfo/*
{
    "code":400,
    "reason":"Bad Request",
    "message":"No requested version specified and behavior set to NONE."
}

If a REST API call does include the Accept-API-Version header, but the specified resource or protocol version does not exist in AM, then a 404 Not Found status code is returned, as shown below:

$ 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":"Accept-API-Version: Requested version \"999.0\" does not match any routes."
}

For more information on setting the default REST API version behavior, see Specify REST API versions.