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


Creating REST Services
Documenting and Discovering REST APIs with API Management
[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 Open API 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. InterSystems IRIS 2018.1 provides a feature, called API Management, that makes it easier to produce an Open API description of your REST APIs. The API Management feature generates an Open API REST description based on the information available in the URLMap definitions. Since 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. The API Management feature also provides a way to discover the REST APIs that are available on an InterSystems IRIS instance.
For example, to generate the documentation for the CoffeeMakerApp REST sample, enter the following REST call:
You can paste the output from this call into the swagger editor. It converts the JSON to YAML (Yet Another Markup Language) and displays the doc. You can use the swagger editor to add more information to the documentation. The swagger editor displays the documentation as shown in the following:
The API Management feature in InterSystems IRIS has the following capabilities:
Discovering REST Web Applications
To discover what REST Web applications are available on an instance, use the following REST call.
If your instance contains the REST Web applications installed with IRIS and the coffeemakerapp application defined in the SAMPLES namespace, the returned data is:
[
  {
    "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
  },
  {
    "name": "/rest/coffeemakerapp",
    "interfaceClass": "demo.CoffeeMakerRESTServer",
    "namespace": "SAMPLES",
    "resource": "",
    "swaggerSpec": "/api/mgmnt/v1/SAMPLES/spec/rest/coffeemakerapp",
    "enabled": true
  }
]