IRIS - apiPub <img src="docResources/apiPub.png" alt="wizard" width="250"/>

Introduction

We are in the multi-platform economy era, and API's are the “glue” of this digital landscape. Being so important, they are seen by developers as a service or product to be consumed. Therefore, the experience in its use is a crucial success factor.

In order to improve this experience, specification standards, such as the Open API Specification (OAS) are increasingly being adopted in the RESTFul API’s development.

What IRIS apiPub is for?

This personal open source project has the main intention to automatically publish RESTful API's built with Intersystems IRIS technology, in the simplest and fastest way possible, using the Open API Specification (OAS 3.0) standard.

Iris apiPub uses the IRIS method specification, and automatically publishes it as a Rest API, allowing customization to make it as friendly as possible for the end user.

It allows the user to focus mainly on the implementation and business rules of API’s (Web Methods), abstracting and automating other aspects related to documentation, exposure, dispatching and monitoring of services.

This project also includes a full IRIS sample class (apiPub.samples.api), based on the official Swagger Petstore sample.

Demo Video:

How an IRIS method is published as a Rest API:

The following table shows how all the method parameters types are mapped and projected to a Rest API:

zpm Installation

Important: It's mandatory to switch to the namespace you want to use before installation.

zn "{namespace}"

zpm "install iris-apipub"

You'll need to install the swagger-ui app for testing.

zpm "install swagger-ui"

You can also enable the monitoring.

docker Prerequisites

Make sure you have git and Docker desktop installed.

docker Installation

Clone/git pull the repo into any local directory

$ git clone https://github.com/devecchijr/apiPub.git

Open the terminal in this directory and run:

$ docker-compose build

Run the IRIS container with your project:

$ docker-compose up -d

Now you can use the apiPub Wizard to automate API publishing

It has the following options to facilitate the publication of APIs:

New APIs based on Templates. It's a great starting point for streamlining the process because it cuts out the manual (3 steps) process, including automating web application creation.
Based on a JSON sample - It automatically creates the schema (OAS) and relates it to the API for input validation (parsing).
Based on an IRIS Production (Interop.). It is possible to choose the component that will be exposed to rest/json API.
Api First Approach (Introspection) - Read an OAS 3.0 specification file and create the Spec of the methods, just like in the apiPub.samples.apiFirst class

If you already install apiPub and swagger-ui apps, you can open the folowing URL.

http://localhost:52773/swagger-ui/index.html?url=http://localhost:52773/apiPub/wizard/IRISAPP/_spec

http://{host:port}/swagger-ui/index.html?url=http://{host:port}/apiPub/wizard/oas/{namespace}/_spec

Publish your OAS 3.0 API in just 3 steps:

Step 1

Define your API’s implementation class and label your methods with the [WebMethod] attribute. If you prefer, use the class apiPub.samples.api (PetStore sample). If you already have a Web Method in place, you can try it.

Step 2

Create a subclass of apiPub.core.service (copy/paste from the following example) and point the DispatchClass parameter to your Implementation class (Step 1). Also inform the OAS documentation path (OASPath parameter).

Class package.name.module Extends apiPub.core.service
{

/// Charset for Output
Parameter CHARSET = "UTF-8";

/// Target path for OAS Documentation
Parameter OASPath As %String = "Get:/_spec";

/// Target class that contains all API (Web Methods) for this module
Parameter DispatchClass As %String = "package.name.api";

/// When the class is also a Business Service
Parameter DispatchBSName;

/// Use IRIS Production to generate tracing and monitoring (dashboards)
Parameter Traceable As %Boolean = 0;

/// Group for monitoring
Parameter APIDomain = "Api Domain";

/// If OASNestedMode=1 publisher avoid name conflict for OAS Schemas (Complex Requests and Responses)
Parameter OASNestedMode = 0;

/// format/prettify the JSON request body
Parameter BeautifyJsonBodyRequest = 0;

/// format/prettify the JSON response body
Parameter BeautifyJsonBodyResponse = 0;

}

Step 3

Create a Web Application and point the Dispatch class to the service class created previously (Step 2).

Use the Swagger

With the iris-web-swagger-ui tool is possible to expose your service specifications. Just point to the documentation path and ... VOILÁ!!

To access the swagger-ui page with the Open Api Specification at once you can use the following request sample (just change the url parameter to your open your OAS path):

http://localhost:52773/swagger-ui/index.html?url=http://localhost:52773/crud/_spec

Test with your existing web methods

If you already have any [WebMethod] implemented, you can try this tool with the same code.

When publishing methods with complex types with native payload schema documentation (OAS), the object class must be a subclass of %JSON.Adaptor or %XML.Adaptor. This way, SOAP web methods already built automatically become compatible. Also it's possible to use %DynamicObjects and relate an OAS schema for documentation and parsing purposes.

Monitor your APIs with IRIS Analytics

Enable API monitoring to manage and track all rest service calls. Also build your own indicators.

Testing the Application

Open swagger URL http://localhost:52773/swagger-ui/index.html

Try to execute some Petstore API's, like Posting a new Pet.

See the apiPub Monitor dashboard. Try to drill down the petStore domain to explore and analyse the service messages.

Change or create methods on the apiPub.samples.api class and turn to see the documentation. Note that all changes are automatically reflected in the documentation or schemas.

Define the OAS header

There are two ways to set the OAS 3.0 header:

The first is by creating a XDATA JSON block named as apiPub in the implementation class. This method allows having more than one Tag (group) and the modeling is compatible with the OAS 3.0 standard. The properties allowed for customization are info, tags and servers.

XData apiPub [ MimeType = application/json ]
{
    {
        "info" : {
            "description" : "This is a sample Petstore server.  You can find\nout more about Swagger at\n[http://swagger.io](http://swagger.io) or on\n[irc.freenode.net, #swagger](http://swagger.io/irc/).\n",
            "version" : "1.0.0",
            "title" : "IRIS Petstore (Dev First)",
            "termsOfService" : "http://swagger.io/terms/",
            "contact" : {
            "email" : "apiteam@swagger.io"
            },
            "license" : {
            "name" : "Apache 2.0",
            "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
            }
        },
        "tags" : [ {
            "name" : "pet",
            "description" : "Everything about your Pets",
            "externalDocs" : {
            "description" : "Find out more",
            "url" : "http://swagger.io"
            }
        }, {
            "name" : "store",
            "description" : "Access to Petstore orders"
        }, {
            "name" : "user",
            "description" : "Operations about user",
            "externalDocs" : {
            "description" : "Find out more about our store",
            "url" : "http://swagger.io"
            }
        } ]
    }
}

The second way is through the definition of parameters in the implementation class, as in the following example:

Parameter SERVICENAME = "My Service";

Parameter SERVICEURL = "http://localhost:52776/apipub";

Parameter TITLE As %String = "REST to SOAP APIs";

Parameter DESCRIPTION As %String = "APIs to Proxy SOAP Web Services via REST";

Parameter TERMSOFSERVICE As %String = "http://www.intersystems.com/terms-of-service/";

Parameter CONTACTNAME As %String = "John Doe";

Parameter CONTACTURL As %String = "https://www.intersystems.com/who-we-are/contact-us/";

Parameter CONTACTEMAIL As %String = "support@intersystems.com";

Parameter LICENSENAME As %String = "Copyright InterS

ApiPub

Install / Use

README