REST API with Swagger in InterSystems IRIS
Hello
The HTTP protocol allows you to obtain resources, such as HTML documents. It is the basis of any data exchange on the Web and a client-server protocol, meaning that requests are initiated by the recipient, usually a Web browser.
REST APIs take advantage of this protocol to exchange messages between client and server. This makes REST APIs fast, lightweight, and flexible. REST APIs use the HTTP verbs GET, POST, PUT, DELETE, and others to indicate the actions they want to perform.
When we make a call to a RESt API, what actually happens is an HTTP call. The API receives this call and according to the requested verb and path, the API performs the desired action. In the case of the Iris implementation we can see this clearly in the URLMap definition area:
XData UrlMap
{
<Routes>
<Route Url="/cliente" Method="POST" Call="Incluir" Cors="true"/>
<Route Url="/cliente/:chave" Method="PUT" Call="Alterar" Cors="true"/>
<Route Url="/cliente/:chave" Method="DELETE" Call="Deletar" Cors="true"/>
<Route Url="/cliente/:chave" Method="GET" Call="Pesquisar" Cors="true"/>
<Route Url="/cliente" Method="GET" Call="Listar" Cors="true"/>
<Route Url="/openapi" Method="GET" Call="OpenAPI" Cors="true"/>
<Route Url="/test" Method="GET" Call="Test" Cors="true"/>
</Routes>
}
Notice that we have the path (Url) and the verb (Method) defined for each call (Call). Thus, the code that meets the API knows what it should do.
This structure in the REST API does not only serve the routing of actions that arrive at the API.
It is also the basis for creating the API Swagger file, as seen in the %REST.API class documentation, GetWebRESTApplication method: https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic....
Let's see how we can generate this documentation then.
First let's publish our API. Let's use the same API as in article https://community.intersystems.com/post/using-rest-api-flask-and-iam-intersystems-iris-part-1-rest-api
Just follow the guidelines and use the code that the article provides to have our API published.
Once the API is published we will include a new route in URLMap and a new method in our code:
<Route Url="/openapi" Method="GET" Call="OpenAPI" Cors="true"/>
ClassMethod OpenAPI() As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set sc = ##class(%REST.API).GetWebRESTApplication("", "/rest/servico", .swagger)
If $$$ISERR(sc) {
Quit sc // If an error occurred, exit the method
}
Write swagger.%ToJSON()
Quit $$$OK
}
Include the new route and the method associated with it in your API code. Let's now do a test. Let's open Postman and call the endpoint for generating Swagger, which is /openapi:
And below we have the complete definition of the Swagger generated by our call:
{
"info": {
"title": "",
"description": "",
"version": "",
"x-ISC_Namespace": "DEMO"
},
"basePath": "/rest/servico",
"paths": {
"/customer": {
"post": {
"parameters": [
{
"name": "payloadBody",
"in": "body",
"description": "Request body contents",
"required": false,
"schema": {
"type": "string"
}
}
],
"operationId": "Include",
"x-ISC_ServiceMethod": "Include",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
},
"get": {
"operationId": "List",
"x-ISC_ServiceMethod": "List",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
}
},
"/customer/{key}": {
"put": {
"parameters": [
{
"name": "key",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "payloadBody",
"in": "body",
"description": "Request body contents",
"required": false,
"schema": {
"type": "string"
}
}
],
"operationId": "Change",
"x-ISC_ServiceMethod": "Change",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
},
"delete": {
"parameters": [
{
"name": "key",
"in": "path",
"required": true,
"type": "string"
}
],
"operationId": "Delete",
"x-ISC_ServiceMethod": "Delete",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
},
"get": {
"parameters": [
{
"name": "key",
"in": "path",
"required": true,
"type": "string"
}
],
"operationId": "Search",
"x-ISC_ServiceMethod": "Search",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
}
},
"/openapi": {
"get": {
"operationId": "OpenAPI",
"x-ISC_ServiceMethod": "OpenAPI",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
}
},
"/test": {
"get": {
"operationId": "Test",
"x-ISC_ServiceMethod": "Test",
"x-ISC_CORS": true,
"responses": {
"default": {
"description": "(Unexpected Error)"
},
"200": {
"description": "(Expected Result)"
}
}
}
}
},
"Swagger": "2.0"
}
The following link gives us access to Iris's documentation that points to a tool that receives the output of our API call and transforms it into a user-friendly interface for documentation and testing of the service: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls...
Let's fire this URL and provide the path to retrieve the Swagger definition from our API: https://swagger.io/tools/swagger-ui/
Let's replace the demo call on the page (the petstore call) with our call: http://127.0.0.1/iris_iss/rest/servico/openapi and see the screen with the generated Swagger documentation:
At the top of the call we have the basic information of our API:
And we can also navigate through the calls and view important information, such as in the POST call to include a new customer:
But, as we saw a little above, the Swagger definition is actually a file in JSON format that is available to us in the form of a %DynamicObject (see documentation in https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic....) after the ##class(%REST.API).GetWebRESTApplication() that we perform in our OpenAPI method. In this way, based on the OpenAPI 2.0 definition we can include or remove information from our Swagger. Let's, for example, enrich the basic information of the API. According to the definition of Version 2.0 (https://swagger.io/specification/v2/ ) we may have the following information made available:
Let's then complete the information that we can make available. To do this, we'll change our OpenAPI method, including the basic information, accepted protocol, authentication, and access data (host and basePath):
ClassMethod OpenAPI() As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set sc = ##class(%REST.API).GetWebRESTApplication("", "/rest/servico", .swagger)
If $$$ISERR(sc) {
Quit sc // If an error occurred, exit the method
}
Set info = {
"title": "Cliente",
"description": "API de Manipulação de Cliente",
"version": "1.00"
}
Do swagger.%Set("info", info)
Do swagger.%Set("host", "127.0.0.1")
Do swagger.%Set("basePath", "/iris_iss/rest/servico")
Set schemes = []
Do schemes.%Push("http")
Do swagger.%Set("schemes", schemes)
Set security = [{"basicAuth":[]}]
Do swagger.%Set("security", security)
Set securityDefinitions = {}
Do securityDefinitions.%Set("basicAuth", {})
Do securityDefinitions.basicAuth.%Set("type", "basic")
Do swagger.%Set("securityDefinitions", securityDefinitions)
Write swagger.%ToJSON()
Quit $$$OK
}
Calling the Swagger documentation again on the preview page now we have the following output:
See that our documentation is much more complete, with more detailed information about the API, such as the authentication mechanism (Basic Auth), the accepted protocol (HTTP) and the version, description and URL definitions.
We can now enrich the definition of the calls by putting the expected structure in the payloads and data examples for the call. To do this, let's overlay the information in paths for "/client":
ClassMethod OpenAPI() As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set sc = ##class(%REST.API).GetWebRESTApplication("", "/rest/servico", .swagger)
If $$$ISERR(sc) {
Quit sc // If an error occurred, exit the method
}
Set info = {
"title": "Cliente",
"description": "API de Manipulação de Cliente",
"version": "1.00"
}
Do swagger.%Set("info", info)
Do swagger.%Set("host", "127.0.0.1")
Do swagger.%Set("basePath", "/iris_iss/rest/servico")
Set schemes = []
Do schemes.%Push("http")
Do swagger.%Set("schemes", schemes)
Set security = [{"basicAuth":[]}]
Do swagger.%Set("security", security)
Set securityDefinitions = {}
Do securityDefinitions.%Set("basicAuth", {})
Do securityDefinitions.basicAuth.%Set("type", "basic")
Do swagger.%Set("securityDefinitions", securityDefinitions)
Set incluirPesquisar = {
"post": {
"summary": "Criar um novo cliente",
"description": "Recebe os dados de um cliente e cadastra no sistema.",
"parameters": [
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"properties": {
"nome": {
"type": "string",
"description": "Nome do cliente"
},
"idade": {
"type": "integer",
"description": "Idade do cliente"
}
},
"required": ["nome", "idade"],
"example": {
"nome": "João Silva",
"idade": 30
}
}
}
],
"responses": {
"default": {
"description": "Falha na chamada da API"
},
"200": {
"description": "Cliente criado com sucesso"
},
"406": {
"description": "Falha na inclusão do cliente"
}
}
},
"get": {
"summary": "Recupera todos os clientes",
"description": "Retorna a lista de clientes com suas informações.",
"responses": {
"default": {
"description": "Falha na chamada da API"
},
"200": {
"description": "Lista de clientes",
"schema": {
"type": "object",
"properties": {
"clientes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"chave": {
"type": "string",
"description": "Chave única do cliente"
},
"nome": {
"type": "string",
"description": "Nome do cliente"
},
"idade": {
"type": "integer",
"description": "Idade do cliente"
}
},
"required": ["chave", "nome", "idade"]
}
}
},
"example": {
"clientes": [
{
"chave": "1",
"nome": "Maria",
"idade": 35
},
{
"chave": "2",
"nome": "Julio",
"idade": 57
},
{
"chave": "4",
"nome": "Julia",
"idade": 25
},
{
"chave": "5",
"nome": "Julia",
"idade": 22
}
]
}
}
}
}
}
}
Do swagger.paths.%Set("/cliente", incluirPesquisar)
Write swagger.%ToJSON()
Quit $$$OK
}
Calling the documentation page again we can now see the POST methods to include a client and GET to retrieve a list:
See that we already have an explanation of what is each of the methods available for POST and GET that we have overwritten.
Note we also no longer have the "x-ISC_ServiceMethod" and "x-ISC_Namespace" tags that we didn't put in our new definition.
Clicking to expand the POST method for example, we now visually have an example call (Example Value):
And the format of the call payload (Model):
In customer recovery, we have the definition of the returned Response with example:
And also with the expected model as an answer:
Also, we can test API calls from the documentation page itself. See the “Try it out” button available on the page. Click on it, then on Execute and see the result:
These possibilities for the Code-first approach of a REST API open up many possibilities for documentation, allowing us to control what will be disseminated, adding or subtracting the information we deem convenient in the published material.
The OpenAPI definition is very complete and detailed. There is a variety of information that we can include or take away, depending on what we need or want to make available in it.
See you next time!
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)