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. For information about the supported resource versions, see the REST API Explorer in the Admin UI. To ensure that your clients are always compatible with a newer IDM 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 "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"

Specifying the API Version in Scripts

You can specify a resource version in JavaScript and Groovy 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

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