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.
For more information about the supported resource versions, see REST API Explorer.
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 "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:
{
"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:
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"
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
infolevel. 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
infolevel.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:
-
Get the current configuration:
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"Default
apiVersionConfiguration{ "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" ] } } -
Make changes, and replace the configuration:
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" : [ <Insert modified resourcePaths here> ] } }' \ "http://localhost:8080/openidm/config/apiVersion"