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&#39;&#39; 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

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:

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 apiVersion Configuration

{
    "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"

IDM 7.2.2

REST API versioning

Specify the API version in REST calls

Specify the API Version in Scripts

API Version Header Warnings

Filter Resource Path Warnings