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 Identity Cloud version, you should always include resource versions in your REST calls.

Specifying 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 *token*" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0" \
--request POST \
--data '{
  "url":"https://www.forgerock.com/favicon.ico",
  "method":"GET"
}' \
"https://tenant-name.forgeblocks.com/openidm/external/rest?_action=call"
Specifying 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 *token*" \
--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\"});"
}' \
"https://tenant-name.forgeblocks.com/openidm/script?_action=eval"

Standalone Javascript
openidm.action("external/rest", "call",
 {"url": "https://www.forgerock.com", "method": "GET"},
 {"Accept-API-Version": "resource=1.0"});

Read a different version of :