Using the ForgeRock IDM API Explorer

ForgeRock Logo This post is part of a series about how to get live reference documentation for ForgeRock REST APIs.

The ForgeRock IDM web-based console includes an API explorer.

The API explorer lets you try out the CREST HTTP APIs as you are building your service. You access the IDM API explorer from the question mark menu in the console. IDM makes many categories of endpoints available. The following example shows the Health category expanded:

IDM browse explorer.png

You can quickly try out one of the API calls. For example, expand /health/memory, and then click the Try it out and Execute buttons:

IDM try health memory endpoint.png

Notice that the API explorer displays everything but the credentials needed to access the REST API.

You can also get the OpenAPI-format API descriptor for the /health endpoint. You pass the _api query string parameter to the endpoint. The resulting OpenAPI descriptor is a JSON document:

curl -u openidm-admin:openidm-admin -o health-api.json http://localhost:8080/openidm/health?_api

To try out the result, download and install Swagger UI, then move the JSON document into the Swagger UI directory. You can then browse the Swagger UI with health-api.json as the descriptor:

IDM Swagger UI.png

The API descriptor that you load from the server no doubt does not exactly match what you need to publish in your live documentation. Use the Swagger Editor to adapt it to your needs:

IDM Swagger Editor.png

For more information, see API Explorer.

Advertisements

One thought on “Using the ForgeRock IDM API Explorer

  1. When trying this out, you might put Swagger UI in a different web server on your laptop. In that case, you need to set up an appropriate CORS filter in IDM.

    For example, I installed IDM with the default ports, e.g. http://localhost:8080, https://localhost:8443. On the same laptop, I installled Swagger UI in Jetty, and started jetty listening on port 8081 (java -Djetty.port=8081 -jar start.jar).

    In order for Swagger UI to work, I added a CORS Servlet filter in IDM:

    cp conf/servletfilter-cors.json conf/servletfilter-cors-swagger.json
    vi conf/servletfilter-cors-swagger.json
    diff conf/servletfilter-cors.json conf/servletfilter-cors-swagger.on
    7c7
             "allowedOrigins" : "http://localhost:8081",
    9c9
             "allowedHeaders" : "accept,x-openidm-password,x-openidm-nosession,x-openidm-username,content-type,origin,x-requested-with,authorization",
    

    Without CORS settings, “Try It Out” won’t work.

    In addition, you need to authenticate to IDM. For evaluation, I authenticated as openidm-admin:openidm-admin. I made this possible in Swagger UI by editing the API descrptor:

    "host":"127.0.0.1" -> "host":"127.0.0.1:8080"
    Added this at the top level: "securityDefinitions":{"basicAuth":{"type":"basic"}},"security":[{"basicAuth":[]}],

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.