--- title: REST API versions description: REST API features are assigned version numbers. component: pingam version: 8.1 page_id: pingam:am-rest:rest-api-versioning canonical_url: https://docs.pingidentity.com/pingam/8.1/am-rest/rest-api-versioning.html keywords: ["REST API", "JSON", "CSRF"] page_aliases: ["REST-guide:rest-api-versioning.adoc"] section_ids: rest-api-explicit-version: Specify REST API versions rest-api-versioning-supported-versions: Supported REST API versions configure-default-version: Configure versioning behavior rest-api-versioning-messages: Version messages --- # 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](../security/rest-CSRF.html). | ## 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: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: bjensen" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate' ``` 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](#configure-default-version). ## Supported REST API versions Find information about the supported protocol and resource versions in the [Online REST API reference](about-api-explorer.html) available in the AM admin UI. The Release notes describe any breaking [changes](https://docs.pingidentity.com/pingam/release-notes/changes.html) 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](https://docs.pingidentity.com/pingam/release-notes/deprecation.html) 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: ```bash $ curl \ -i \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: bjensen" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://am.example.com:8443/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":"/am/console" } ``` 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: ```bash $ curl \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/serverinfo/*' { "code": 404, "reason": "Not Found", "message": "Resource '*' not found" } ``` 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: ```bash $ curl \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=1.0, resource=999.0" \ 'https://am.example.com:8443/am/json/realms/root/serverinfo/*' { "code": 404, "reason": "Not Found", "message": "Resource '*' not found" } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------- | | | Find information on setting the default REST API version behavior in [Specify REST API versions](#rest-api-explicit-version). |