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
tomessage
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
|
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."
}