IDM 7.3.1

REST API Explorer

IDM includes an API Explorer, an implementation of the OpenAPI Initiative Specification, also known as Swagger.

The API Explorer covers most endpoints provided with a default IDM installation.

Each endpoint lists supported HTTP methods, such as POST and GET. When custom actions are available, the API Explorer lists them as:

HTTP Method /path/to/endpoint?_action=something

Example

To see the API Explorer in action, follow along with this procedure:

  1. To access the API Explorer, log in to the admin UI, click the question mark button in the upper right corner, and select API Explorer.

    If the API Explorer does not display, you might need to enable it in your resolver/boot.properties file by setting the openidm.apidescriptor.enabled property to true.

  2. Expand the User v1.0 endpoint node, and click GET /openidm/managed/user1.0_query_id_query-all.

    API Explorer - User Node

  3. Click Try it out!, and then click Execute.

    The output includes:

    • The REST call, in the form of the curl command.

    • The request URL, which specifies the endpoint and associated parameters.

    • The response body, which contains the data that you requested.

    • The HTTP response code; if everything works, this should be 200.

      If you refer to a 401 Access Denied code in the response body, your session may have timed out, and you’ll have to log in to the admin UI again.

    • Response headers.

    Example Output

    apiExpOutput

For details on common ForgeRock REST parameters, refer to ForgeRock Common REST.

You’ll refer to examples of REST calls throughout this documentation set. You can try these calls with the API Explorer.

You can also generate an OpenAPI-compliant descriptor of the REST API to provide API reference documentation specific to your deployment. The following command saves the API descriptor of the managed/user endpoint to a file named my-openidm-api.json:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
--output "my-openidm-api.json" \
"http://localhost:8080/openidm/managed/user?_api"

For information about publishing reference documentation using the API descriptor, refer to Publish OpenAPI Documentation.