--- title: REST API versioning description: ForgeRock 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 ForgeRock introduces a change that is not backwards-compatible, and that affects clients that use the feature. component: pingoneaic page_id: pingoneaic:idm-rest-api:rest-api-versioning canonical_url: https://docs.pingidentity.com/pingoneaic/idm-rest-api/rest-api-versioning.html 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 ForgeRock 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 ForgeRock introduces a change that is not backwards-compatible, and that affects clients that 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. ## 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 *latest* resource version is invoked by the HTTP request. The following call requests version `2.0` of the specified resource: ``` curl \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.0" \ --request POST \ --data '{ "url":"https://www.pingidentity.com/favicon.ico", "method":"GET" }' \ "https:///openidm/external/rest?_action=call" ``` ## 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 "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type":"text/javascript", "source":"openidm.action(\"external/rest\", \"call\", {\"url\": \"https://www.pingidentity.com/favicon.ico\", \"method\": \"GET\"}, {\"Accept-API-Version\": \"resource=1.0\"});" }' \ "https:///openidm/script?_action=compile" ``` Standalone Javascript ```javascript openidm.action("external/rest", "call", {"url": "https://www.pingidentity.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, set one or more of the following properties: * `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 `apiVersion` configuration: 1. Get the current configuration: ```none curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/config/apiVersion" ``` > **Collapse: Default Configuration** > > ```json > { > "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/alpha_assignment", > "managed/alpha_organization", > "managed/alpha_role", > "managed/alpha_user", > "managed/alpha_usermeta", > "managed/alpha_group", > "managed/alpha_application", > "managed/bravo_assignment", > "managed/bravo_organization", > "managed/bravo_role", > "managed/bravo_user", > "managed/bravo_usermeta", > "managed/bravo_group", > "managed/bravo_application", > "managed/teammember", > "managed/teammembermeta", > "managed/svcacct", > "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 "Authorization: Bearer " \ --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" : [ ] } }' \ "https:///openidm/config/apiVersion" ```