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

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 \
-i \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Secret12!" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'

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: Secret12!" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/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://<tenant-env-fqdn>/am/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://<tenant-env-fqdn>/am/json/realms/root/serverinfo/*'
{
    "code":404,
    "reason":"Not Found",
    "message":"Accept-API-Version: Requested version \"999.0\" does not match any routes."
}

Identity Cloud

REST API versions

Specify REST API versions

Version messages