How To

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

Last updated Oct 12, 2020

The purpose of this article is to provide information on generating API documentation for IDM custom endpoints.


1 reader recommends this article

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.

Note

If you want to add "If-None-Match" and "If-Match" header parameters to Read requests and Delete/Patch requests, you should set the mvccSupported property to 'true'. You do not need to add “if-match” and “if-none-match” specifically to the request parameters.

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)



Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.
Loading...