How do I generate API documentation for custom endpoints in IDM 5.5.x, 6.x and 7.x?

Overview

The IDM API Explorer provides API documentation for IDM’s default endpoints, for example:

However, documentation is not automatically generated for custom endpoints. You can use the API Explorer to generate reference documentation for custom endpoints by including an apiDescription field in the endpoint’s configuration file.

Generating API documentation for custom endpoints example

The following example demonstrates how to do this for the sample custom endpoint (echo) and assumes you have already created the custom endpoint. See Samples Guide › Create a Custom Endpoint for further information.

You can generate API documentation for a custom endpoint as follows:

1. Add the apiDescription field to the endpoint configuration file (/path/to/idm/conf/endpoint-echo.json in this example) to include all the actions and queries you want documented. See Forgerock Wiki - Defining API Descriptors for further assistance.

   For example:

   {
       "file" : "echo.groovy",
       "type" : "groovy",
       "_file" : "echo.js",
       "_type" : "text/javascript",
       "apiDescription" : {
           "title" : "Echo",
           "description" : "Service that echo's your HTTP requests.",
           "mvccSupported" : true,
           "create" : {
               "description" : "Echo a CREATE request.",
               "mode" : "ID_FROM_SERVER",
               "singleton" : false
           },
           "read" : {
   	       	"description" : "Echo a READ request." }, 		
           "update" : { "description" : "Echo an UPDATE request." },
           "delete" : { "description" : "Echo a DELETE request." },
           "patch" : {
               "description" : "Echo a PATCH request.",
               "operations" : [ "ADD", "REMOVE", "REPLACE", "INCREMENT", "COPY", "MOVE", "TRANSFORM" ]
           },
           "actions" : [
               {
                   "description" : "Echo an ACTION request.",
                   "name" : "echo",
                   "request" : { "type" : "object" },
                   "response" : {
                       "title" : "Echo action response",
                       "type" : "object",
                       "properties" : {
                           "method" : {
                               "type" : "string",
                               "enum" : [ "action" ]
                           },
                           "action" : { "type" : "string" },
                           "content" : { "type" : "object" },
                           "parameters" : { "type" : "object" },
                           "context" : { "type" : "object" }
                       }
                   }
               }
           ],
           "queries" : [
               {
                   "description" : "Echo a query-filter request.",
                   "type" : "FILTER",
                   "queryableFields" : [ "*" ]
               },
               {
                   "description" : "Echo a query-all request.",
                   "type" : "ID",
                   "queryId" : "query-all"
               },
               {
                   "description" : "Echo a query-all-ids request.",
                   "type" : "ID",
                   "queryId" : "query-all-ids"
               }
           ],
           "resourceSchema" : {
               "title" : "Echo resource",
               "type" : "object",
               "properties" : {
                   "method" : {
                       "title" : "CREST method",
                       "type" : "string"
                   },
                   "resourceName" : { "type" : "string" },
                   "parameters" : { "type" : "object" },
                   "context" : { "type" : "object" }
               }
           }
       }
   }
   

2. Review the API Explorer to check that your custom endpoint is now included, for example:

   

See Also

REST API Reference › REST API Explorer

Scripting Guide › Create Custom Endpoints to Launch Scripts

Forgerock Wiki - Defining API Descriptors

Using the ForgeRock IDM API Explorer

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-12996 (DOCS: API Descriptor for scripted custom endpoint)