Listing and Documenting REST APIs
This topic discusses how to discover the REST services that are available on an instance and how to generate documentation for REST services.
Using the /api/mgmnt Service to Discover REST Services
The /api/mgmnt service includes calls you can use to discover REST service classes and REST-enabled web applications.
Discovering REST Services
To use the /api/mgmnt service to discover the REST services that are available on an instance, use the following REST call:
-
For the HTTP action, select or specify GET.
-
For the URL, specify a URL of the following form, using the <baseURL> for your instance:
http://<baseURL>/api/mgmnt/v2/
Or, if you want to examine only one namespace:
http://<baseURL>/api/mgmnt/v2/:namespace
Where namespace is the namespace you want to examine.
(Note that these calls ignore manually-coded REST services. To discover manually-coded REST applications, use the calls GET /api/mgmnt/ and GET /api/mgmnt/:v1/:namespace/restapps.)
If the call is successful, InterSystems IRIS returns an array that lists the REST services, in JSON format. For example:
[
{
"name": "%Api.Mgmnt.v2",
"webApplications": "/api/mgmnt",
"dispatchClass": "%Api.Mgmnt.v2.disp",
"namespace": "%SYS",
"swaggerSpec": "/api/mgmnt/v2/%25SYS/%Api.Mgmnt.v2"
},
{
"name": "myapp",
"webApplications": "/api/myapp",
"dispatchClass": "myapp.disp",
"namespace": "USER",
"swaggerSpec": "/api/mgmnt/v2/USER/myapp"
}
]
Discovering REST-Enabled Web Applications
To use the /api/mgmnt service to discover the REST-enabled web applications that are available on an instance, use the following REST call:
-
For the HTTP action, select or specify GET.
-
For the URL, specify a URL of the following form, using the <baseURL> for your instance:
http://<baseURL>/api/mgmnt
Or, if you want to examine only one namespace:
http://<baseURL>/api/mgmnt/v1/:namespace/restapps
Where namespace is the namespace you want to examine.
See the reference sections for GET /api/mgmnt/ and GET /api/mgmnt/:v1/:namespace/restapps.
Using the %REST.API Class to Discover REST Services
The %REST.APIOpens in a new tab class provides methods you can use to discover REST service classes and REST-enabled web applications.
Discovering REST Service Classes
To use the %REST.APIOpens in a new tab class to discover the REST services that are available on an instance, use the following methods of that class:
GetAllRESTApps(Output appList As %ListOfObjects) as %Status
Returns, as output, a list of the REST services on this server. The output argument applist is an instance of %ListOfObjectsOpens in a new tab, and each item in the list is an instance of %REST.ApplicationOpens in a new tab that contains information about the REST service. This includes any REST services that do not have an associated web application. This method ignores any manually-coded REST services.
GetRESTApps(namespace as %String,
Output appList As %ListOfObjects) as %Status
Returns, as output, a list of the REST services in the namespace indicated by namepace. See GetAllWebRESTApps(). See GetAllRESTApps().
Discovering REST-Enabled Web Applications
To use the %REST.APIOpens in a new tab class to discover the REST-enabled web applications that are available on an instance, use the following methods of that class:
GetAllWebRESTApps(Output appList As %ListOfObjects) as %Status
Returns, as output, a list of the REST-enabled web applications on this server. The output argument applist is an instance of %ListOfObjectsOpens in a new tab, and each item in the list is an instance of %REST.ApplicationOpens in a new tab that contains information about web application.
GetWebRESTApps(namespace as %String,
Output appList As %ListOfObjects) as %Status
Returns, as output, a list of the REST-enabled web applications in the namespace indicated by namepace. See GetAllWebRESTApps().
Providing Documentation for a REST Service
It is useful to document any API so that developers can easily use the API. In the case of a REST API that follows the OpenAPI 2.0 specificationOpens in a new tab, you can use the SwaggerOpens in a new tab open-source framework to provide interactive documentation for your API, based upon the contents of the specification.
One option is to use Swagger UIOpens in a new tab and provide a hosted copy of the documentation. For a demo:
-
Go to https://swagger.io/tools/swagger-ui/Opens in a new tab
-
Click Live Demo.
-
In the box at the top of the page, enter the URL of the OpenAPI 2.0 specificationOpens in a new tab for the REST service, in JSON format.
For example, use the GET /api/mgmnt/v2/:namespace/:application call on the InterSystems IRIS server.
-
Click Explore.
The lower part of the page then displays the documentation as shown in the following example:
Here you can view details about each call, try test calls and see the responses. For more details, see the SwaggerOpens in a new tab web site.
Other third-party tools enable you to generate static HTML. InterSystems has no specific recommendations for this.
