PingGateway API descriptors

Common REST endpoints in PingGateway serve API descriptors at runtime.

When you get an API descriptor for an endpoint, PingGateway returns a resource describing the APIs at the endpoint and any child endpoints. Use the API descriptor with an OpenAPI tool like Swagger UI to generate documentation.

When you start PingGateway or add or edit routes, PingGateway records endpoint locations in the PingGateway logs/route-system.log file and endpoint locations for subroutes in the specific log files for the routes.

To get the API descriptor for a specific endpoint, PingGateway must be in development mode. Make an HTTP GET request to the endpoint with one of the following query string parameters:

_api for the API accessible over HTTP.

You can get this API descriptor for partial URLs.

The JSON API descriptor follows the OpenAPI specification.
_crestapi for a proprietary, compact representation independent of the transport protocol.

You can’t get this API descriptor for partial URLs.

The JSON API descriptor follows the proprietary specification for Common REST endpoints.

Learn more in Common REST API documentation.

Get API descriptors for a router

Switch to development mode to get API descriptors.

With PingGateway running as described in Getting started with PingGateway, use the following query to get an API descriptor for the router:

$ curl http://ig.example.com:8085/api/system/objects/_router/routes\?_api

Output

{
     "swagger": "2.0",
     "info": {
          "version": "2025.6.0",
          "title": "PingGateway"
     },
     "host": "0:0:0:0:0:0:0:1",
     "basePath": "/api/system/objects/_router/routes",
     "tags": [
          {
               "name": "Routes Endpoint"
          }
     ],
     "...": "..."
}

Alternatively, get a Common REST API descriptor with the ?_crestapi query string.

Get an API descriptor for the UMA service

Switch to development mode to get API descriptors.

With the UMA tutorial running as described in UMA support with PingAM, use the following query to get an API descriptor for the UMA share API:

$ curl http://ig.example.com:8085/api/system/objects/_router/routes/00-uma/objects/umaservice/share\?_api

Output

{
     "swagger": "2.0",
     "info": {
          "version": "2025.6.0",
          "title": "PingGateway"
     },
     "host": "0:0:0:0:0:0:0:1",
     "basePath": "/api/system/objects/_router/routes/00-uma/objects/umaservice/share",
     "tags": [
          {
               "name": "Manage UMA Share objects"
          }
     ],
     "...": "..."
}

Alternatively, get a Common REST API descriptor with the ?_crestapi query string.

Get an API descriptor for the main router

Switch to development mode to get API descriptors.

With PingGateway running, use the following query to get an API descriptor for the main router and child endpoints:

$ curl http://ig.example.com:8085/api/system/objects/_router\?_api

Output

{
     "swagger": "2.0",
     "info": {
          "version": "2025.6.0",
          "title": "PingGateway"
     },
     "host": "ig.example.com:8085",
     "basePath": "/api/system/objects/_router",
     "tags": [
          {
               "name": "Monitoring endpoint"
          },
          {
               "name": "Manage UMA Share objects"
          },
          {
               "name": "Routes Endpoint"
          }
     ],
     "...": "..."
}

The above URL is a partial URL, so you can’t use the ?_crestapi query string to get a Common REST API descriptor.

Get an API descriptor for PingGateway instances

Switch to development mode to get API descriptors.

With a PingGateway instance running, use the following query to get an API descriptor:

$ curl http://ig.example.com:8085/api\?_api

Output

{
     "swagger": "2.0",
     "info": {
          "version": "2025.6.0",
          "title": "PingGateway"
     },
     "host": "ig.example.com:8085",
     "basePath": "/api",
     "tags": [
          {
               "name": "Internal Storage for UI Models"
          },
          {
               "name": "Monitoring endpoint"
          },
          {
               "name": "Manage UMA Share objects"
          },
          {
               "name": "Routes Endpoint"
          },
          {
               "name": "Server Info"
          }
     ],
     "...": "..."
}

If you add routes after the request is performed, run the query again to get the updated API descriptor.

The above URL is a partial URL, so you can’t use the ?_crestapi query string to get a Common REST API descriptor.