docs.intersystems.com
Home  /  Application Development: Additional Options  /  Creating REST Services  /  Discovering and Documenting REST APIs


Creating REST Services
Discovering and Documenting REST APIs
[Back] 
InterSystems: The power behind what matters   
Search:  


It is useful to document REST APIs so that developers can easily develop applications that call these APIs. The OpenAPI 2.0 Spec and tools such as Swagger provide a standard mechanism to document REST APIs and provide a framework to test and develop applications that call REST APIs.
In IRIS, the API management features make it easier to produce an Open 2.0 API description of your REST APIs. These features also provides a way to discover the REST APIs that are available on an InterSystems IRIS instance.
This chapter discusses how to use the API management features. It discusses the following topics:
Discovering REST-Enabled Web Applications
To discover the REST-enabled web applications that are available on an instance, use the following REST call:
For example, the /api/mgmnt call returns the following:
[
  {
    "name": "/api/atelier",
    "interfaceClass": "%Api.Atelier",
    "namespace": "%SYS",
    "resource": "%Development",
    "swaggerSpec": "/api/mgmnt/v1/%25SYS/spec/api/atelier",
    "enabled": true
  },
  {
    "name": "/api/deepsee",
    "interfaceClass": "%Api.DeepSee",
    "namespace": "%SYS",
    "resource": "",
    "swaggerSpec": "/api/mgmnt/v1/%25SYS/spec/api/deepsee",
    "enabled": true
  },
  {
    "name": "/api/docdb",
    "interfaceClass": "%Api.DocDB",
    "namespace": "%SYS",
    "resource": "",
    "swaggerSpec": "/api/mgmnt/v1/%25SYS/spec/api/docdb",
    "enabled": true
  },
  {
    "name": "/api/iknow",
    "interfaceClass": "%Api.iKnow",
    "namespace": "%SYS",
    "resource": "",
    "swaggerSpec": "/api/mgmnt/v1/%25SYS/spec/api/iknow",
    "enabled": true
  },
  {
    "name": "/api/mgmnt",
    "interfaceClass": "%Api.Mgmnt",
    "namespace": "%SYS",
    "resource": "%Development",
    "swaggerSpec": "/api/mgmnt/v1/%25SYS/spec/api/mgmnt",
    "enabled": true
  },
  {
    "name": "/api/uima",
    "interfaceClass": "%Api.UIMA",
    "namespace": "%SYS",
    "resource": "",
    "swaggerSpec": "/api/mgmnt/v1/%25SYS/spec/api/uima",
    "enabled": true
  }
]
Generating Documentation for a REST Service
It is useful to document REST APIs so that developers can easily develop applications that call these APIs. To generate documentation for a REST service, do the following:
  1. Use the following REST call:
  2. Copy the output from this call into the Swagger editor, which converts the JSON to YAML (Yet Another Markup Language) and displays the documentation.
    The Swagger editor displays the documentation as shown in the following example:
    This Open API description is based on the information available in the URLMap definitions. Because the URLMap does not contain information such as the payload description and HTTP return values, you need to edit the generated documentation to add this information.
  3. Use the Swagger editor to add to the documentation.
Enabling Logging
To enable logging for the API management feature, enter the following in the Terminal:
 zn "%SYS"
 kill ^ISCLOG
 set ^%ISCLOG=5
 set ^%ISCLOG("Category","apimgmnt")=5
Then the system adds entries to the ^ISCLOG global for any calls to the API management endpoints.
To write the log to a file (for easier readability), enter the following (still within the %SYS namespace):
 do ##class(%OAuth2.Utils).DisplayLog("filename")
Where filename is the name of the file to create. The directory must already exist. If the file already exists, it is overwritten.
To stop logging, enter the following (still within the %SYS namespace):
 set ^%ISCLOG=0
 set ^%ISCLOG("Category","apimgmnt")=0