--- title: REST API versioning description: Ping 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 Ping introduces a change that is not backwards-compatible and affects clients who use the feature. component: pingidm version: 8.1 page_id: pingidm:rest-api-reference:rest-api-versioning canonical_url: https://docs.pingidentity.com/pingidm/8.1/rest-api-reference/rest-api-versioning.html keywords: ["REST API"] section_ids: api-version-over-rest: Specify the API version in REST calls api-version-in-scripts: Specify the API Version in Scripts api_version_header_warnings: API Version Header Warnings filter_resource_path_warnings: Filter Resource Path Warnings --- # REST API versioning Ping 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 Ping introduces a change that is not backwards-compatible and affects clients who use the feature. If there is more than one version of the API, you must select the version by setting a version header that specifies which version of the *resource* is requested. To ensure that your clients are always compatible with a newer IDM version, you should always include resource versions in your REST calls. For more information about the supported resource versions, refer to [REST API Explorer](api-explorer.html). ## Specify the API version in REST calls HTTP requests can optionally include the `Accept-API-Version` header with the value of the resource version, such as `resource=2.0`. If no `Accept-API-Version` header is included, the request defaults to API version `1.0`. The `consent`, `scheduler/job`, `scheduler/trigger`, and `schema` endpoints default to API version `2.0`. The following call requests version `2.0` of the specified resource: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ --data '{ "url":"https://www.forgerock.com/favicon.ico", "method":"GET" }' \ "http://localhost:8080/openidm/external/rest?_action=call" ``` If `Accept-API-Version` contains an invalid version, IDM returns the following error: ```json { "code": 404, "reason": "Not Found", "message": "Resource'' not found" } ``` ## Specify the API Version in Scripts You can specify a resource version in scripts using the fourth (*additional parameters*) argument. If present, the `Accept-API-Version` parameter is applied to the actual REST request. Any other parameters are set as Additional Parameters on the request. The following examples request specific resource versions: REST with Inline Javascript ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type":"text/javascript", "source":"openidm.action(\"external/rest\", \"call\", {\"url\": \"https://www.forgerock.com/favicon.ico\", \"method\": \"GET\"}, {\"Accept-API-Version\": \"resource=1.0\"});" }' \ "http://localhost:8080/openidm/script?_action=eval" ``` Standalone Javascript ```javascript openidm.action("external/rest", "call", {"url": "https://www.forgerock.com/favicon.ico", "method": "GET"}, {"Accept-API-Version": "resource=1.0"}); ``` ## API Version Header Warnings IDM can log warnings when API version headers are not specified. Additionally, you can enable warnings when *scripts* don't specify API versions. Warnings are disabled by default. To enable this feature, add one or more of the following to your project's `resolver/boot.properties` file: * `openidm.apiVersion.warning.enabled=true` * A message will be logged once per resource path, at the `info` level. For example: ``` INFO: Accept-API-Version header missing from external request (authentication); transactionId=e017258a-8bac-4507-9575-78a41152e479-1929 ``` * The HTTP response will apply a warning header. For example: ``` Warning: 100 CREST "Accept-API-Version should be included in the request." ``` * `openidm.apiVersion.warning.includeScripts=true` | | | | - | ---------------------------------------------------------------- | | | This setting requires `openidm.apiVersion.warning.enabled=true`. | * A message will be logged once per resource path *and* script-name pair, at the `info` level. Example script file log entry: ``` [127] Sep 22, 2021 4:08:15.162 AM org.forgerock.openidm.servlet.internal.ResourceApiVersionFilterRegistration logOnceForScriptRequest INFO: Accept-API-Version header missing from script (policyFilter.js) request: policy ``` Example inline script log entry: ``` INFO: Accept-API-Version header missing from script (d6fc81179beaca37094a23c2fcd00aaf54bb3ef9:router:onRequest) request (config) ... INFO: Accept-API-Version header missing from script (policy.js) request (managed/user) ``` ### Filter Resource Path Warnings To filter which resource paths are logged, edit the `logFilterResourcePaths` array located in the `conf/apiVersion.json` file. You can also modify the configuration over REST: 1. Get the current configuration: ```none curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/config/apiVersion" ``` > **Collapse: Default Configuration** > > ```json > { > "_id": "apiVersion", > "warning": { > "enabled": { > "$bool": "&{openidm.apiVersion.warning.enabled|false}" > }, > "includeScripts": { > "$bool": "&{openidm.apiVersion.warning.includeScripts|false}" > }, > "logFilterResourcePaths": [ > "audit", > "authentication", > "cluster", > "config", > "consent", > "csv", > "external/rest", > "identityProviders", > "info", > "internal", > "internal/role", > "internal/user", > "internal/usermeta", > "managed", > "managed/assignment", > "managed/organization", > "managed/role", > "managed/user", > "notification", > "policy", > "privilege", > "profile", > "recon", > "recon/assoc", > "repo", > "selfservice/kba", > "selfservice/terms", > "scheduler/job", > "scheduler/trigger", > "schema", > "sync", > "sync/mappings", > "system", > "taskscanner" > ] > } > } > ``` 2. Make changes, and replace the configuration: ```none curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "warning" : { "enabled" : { "$bool" : "&{openidm.apiVersion.warning.enabled|false}" }, "includeScripts" : { "$bool" : "&{openidm.apiVersion.warning.includeScripts|false}" }, "logFilterResourcePaths" : [ ] } }' \ "http://localhost:8080/openidm/config/apiVersion" ```