---
title: REST API versions
description: Versioning in the REST APIs helps ensure compatibility between releases. The version number of a feature increases for each non-backwards-compatible change.
component: pingoneaic
page_id: pingoneaic:am-rest:rest-api-versioning
canonical_url: https://docs.pingidentity.com/pingoneaic/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 versions
  rest-api-versioning-messages: Version messages
---

# REST API versions

Versioning in the REST APIs helps ensure compatibility between releases. The version number of a feature increases for each non-backwards-compatible change.

|   |                                                                                                                                                                                                                                                                                                                                                                                                                              |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Always include *resource* versions in your REST calls. This ensures your applications remain compatible when Advanced Identity Cloud is updated.Advanced Identity Cloud has cross-site request forgery (CSRF) protection for all the endpoints under `/am/json`. This protection requires all requests other than GET, HEAD, or OPTIONS to include one of the following headers:- `Accept-API-Version`

- `X-Requested-With` |

## Specify versions

REST APIs use the `Accept-API-Version` header to specify protocol and resource versions:

Accept-API-Version: protocol=*version*,resource=*version*

* `protocol`

  The version reflects changes in the REST protocol, such as common method parameters and headers specified by the protocol itself, or the input or response conventions it prescribes.

  For example, protocol version 2.2 introduced a `_countOnly` parameter.

* `resource`

  The version reflects changes in the resource implementation, including JSON representation of resources, input parameters required, and incompatible behavior changes.

  For example, the version changes when `errorMessage` changes to `message` in a JSON response.

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: Secret12!" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
```

## Version messages

REST API responses include a `content-api-version` header to indicate the resource or protocol versions used to service the request. The following example shows a request for a version 2.0 resource and a response including a version 2.1 resource:

```bash
$ curl \
--request POST \
--include \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--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'
...
content-api-version: resource=2.1
...
```

When the request has an incomplete version specification or is missing the header, the response includes a `warning` header:

```bash
$ curl \
--request POST \
--include \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
...
content-api-version: resource=2.1
warning: 100 OpenAM REST "No Accept-API-Version specified"
warning: 100 chf "Accept-API-Version should be included in the request."
...
```

If the version specification prevents Advanced Identity Cloud from serving the request, the response status is HTTP 404 Not Found and the response headers are not included:

```bash
$ curl \
--request POST \
--include \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
--header "Accept-API-Version: resource=42.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
HTTP/2 404
...
```

In this error case the response body is empty.