Using the ForgeRock AM API Explorer

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

The ForgeRock AM 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 AM API explorer from the question mark menu in the console:

AM API explorer.png

By default, there are many APIs published in the top-level realm. A simple one that you can try right away when logged in as AmAdmin is an action on the /sessions endpoint. Click /sessions in the left menu, scroll down, and click /sessions#1.2_query_id_all:

AM browse API explorer.png

Next, scroll to and click the Try it out! button:

AM try sessions endpoint.png

Notice that the API explorer displays everything but the AM SSO details that your browser is using to authenticate with your AmAdmin session.

Suppose you want to get the OpenAPI-format API descriptor for the /sessions endpoint. You pass the _api query string parameter to the endpoint. The resulting OpenAPI descriptor is a JSON document:

curl -o sessions-api.json http://openam.example.com:8080/openam/json/sessions?_api

To try out the result, download and install Swagger UI, then move the JSON document into the Swagger UI directory.

For example, copy the Swagger UI dist folder into the same Apache Tomcat server used by OpenAM, add the descriptor, and restart Tomcat:

unzip swagger-ui-version.zip
cp -r swagger-ui-version/dist /path/to/tomcat/webapps/swagger-ui
mv sessions-api.json /path/to/tomcat/webapps/swagger-ui/
/path/to/tomcat/bin/shutdown.sh
/path/to/tomcat/bin/startup.sh

Now browse http://openam.example.com:8080/swagger-ui/ with http://openam.example.com:8080/swagger-ui/sessions-api.json as the descriptor:

AM 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:

AM Swagger Editor.png

For more information, see Introducing the API Explorer. For details about authenticating to use the APIs outside the console, see Authentication and Logout.

Advertisements

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.