Understanding IG APIs With API Descriptors
Common REST endpoints in IG serve API descriptors at runtime. When you retrieve an API descriptor for an endpoint, a JSON that describes the API for that endpoint is returned.
To help you discover and understand APIs, you can use the API descriptor with a tool such as Swagger UI to generate a web page that helps you to view and test the different endpoints.
When you start IG, or add or edit routes, registered endpoint locations for the routes hosted by the main router are written in $HOME/.openig/logs/route-system.log, where $HOME/.openig is the instance directory. Endpoint locations for subroutes are written to other log files. To retrieve the API descriptor for a specific endpoint, append one of the following query string parameters to the endpoint:
_api, to represent the API accessible over HTTP. This OpenAPI descriptor can be used with endpoints that are complete or partial URLs.The returned JSON respects the OpenAPI specification and can be consumed by Swagger tools, such as Swagger UI.
_crestapi, to provide a compact representation that is independent of the transport protocol. This ForgeRock® Common REST (Common REST) API descriptor cannot be used with partial URLs.The returned JSON respects a ForgeRock proprietary specification dedicated to describe Common REST endpoints.
For more information about Common REST API descriptors, see "Common REST API Documentation".
With IG running as described in the Getting Started Guide, run the following query to generate a JSON that describes the router operations supported by the endpoint:
http://openig.example.com:8080/openig/api/system/objects/_router/routes?_api{ "swagger": "2.0", "info": { "version": "IG version", "title": "IG" }, "host": "0:0:0:0:0:0:0:1", "basePath": "/openig/api/system/objects/_router/routes", "tags": [{ "name": "Routes Endpoint" }], . . .
Alternatively, generate a Common REST API descriptor by using the ?_crestapi query string.
With the UMA tutorial running as described in Supporting UMA Resource Servers, run the following query to generate a JSON that describes the UMA share API:
http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share?_api{ "swagger": "2.0", "info": { "version": "IG version", "title": "IG" }, "host": "0:0:0:0:0:0:0:1", "basePath": "/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share", "tags": [{ "name": "Manage UMA Share objects" }], . . .
Alternatively, generate a Common REST API descriptor by using the ?_crestapi query string.
Run a query to generate a JSON that describes the API for the main router and its subsequent endpoints. For example:
http://openig.example.com:8080/openig/api/system/objects/_router?_api{ "swagger": "2.0", "info": { "version": "IG version", "title": "IG" }, "host": "openig.example.com:8080", "basePath": "/openig/api/system/objects/_router", "tags": [{ "name": "Monitoring endpoint" }, { "name": "Manage UMA Share objects" }, { "name": "Routes Endpoint" }], . . .
Because the above URL is a partial URL, you cannot use the ?_crestapi query string to generate a Common REST API descriptor.
Run a query to generate a JSON that describes the APIs provided by the IG instance that is responding to a request. For example:
http://openig.example.com:8080/openig/api?_api{ "swagger": "2.0", "info": { "version": "IG version", "title": "IG" }, "host": "openig.example.com:8080", "basePath": "/openig/api", "tags": [{ "name": "Internal Storage for UI Models" }, { "name": "Monitoring endpoint" }, { "name": "Manage UMA Share objects" }, { "name": "Routes Endpoint" }, { "name": "Server Info" }], . . .
If routes are added after the request is performed, they are not included in the returned JSON.
Because the above URL is a partial URL, you cannot use the ?_crestapi query string to generate a Common REST API descriptor.