In this article, I will share the theme we presented at the Global Summit 2023, in the Tech Exchange room. Me and @Rochael.Ribeiro
In this opportunity, we talk about the following topics:
- Open Exchange Tools for Fast APIs
- Open API Specification
- Traditional versus Fast Api development
- Composite API (Interoperability)
- Spec-First or Api-First Approach
- Api Governance & Monitoring
- Demo (video)
As we are talking about fast modern APIs development (Rest / json) we will use two Intersystems Open Exchange tools:
The first is a framework for rapid development of APIs which we will detail in this article.
The second is to use Swagger as a user interface for the specification and documentation of the Rest APIs developed on IRIS platform, as well as their use/execution. The basis for its operation is the Open Api specification (OAS) standard, described below:
It is a standard used worldwide to define, document and consume APIs. In most cases, APIs are designed even before implementation. I'll talk more about it in the next topics.
It is important because it defines and documents Rest APIs for its use, both on the provider and consumer side. But this pattern also serves to speed up tests and API calls in tools (Rest APIs Clients) on the market, such as Swagger, Postman, Insomnia, etc…
Imagine we have to build and publish a Rest API from an existing IRIS method (picture below).
In the traditional way:
1: We have to think about how consumers will call it. For example: Which path and verb will be used and how will be the response. Whether in a JSON object or as a plain/text.
2: Build a new method in a %CSP.REST class that will handle the http request to call it.
3: Handle the method's response to the intended http response for the end user.
4: Think about how we're going to provide the success code and how we're going to handle exceptions.
5: Map the route for our new method.
6: Provide the API documentation to the end user. We will probably build the OAS content manually.
7: And if, for example, we have a request or response payload (object), the implementation time will increase, because it must also be documented in OAS.
By simply tagging the IRIS method with the [WebMethod] attribute. Whatever it is, the framework will take care of its publication, using the OAS 3.x standard.
Because It also documents in detail all properties of the input and output payloads.
In this way, any Rest Client tools on the market can instantly couple to the APIs, Like Insomnia, Postman, Swagger, etc. and provide a sample content to call them easily.
But what if I need to customize my API?
For example: Instead of the name of the method I want the path to be something else. And I want the input parameters to be in the path, not like a query param.
We define a specific notation on top of the method, where we can complement the meta-information that the method itself does not provide.
This framework supports numerous types of parameters.
In this map we can highlight the complex types (the objects). They will be automatically exposed as a JSON payload and each property will be properly documented (OAS) for the end user .
By supporting complex types, you can also expose Interoperability Services.
It is a favorable scenario for building composite APIs, which use the orchestration of multiple external components (outbounds).
This means that objects or messages used as request or response will be automatically published and read by tools like swagger.
And it's an excellent way to test interoperability components, because usually a payload template is already loaded so that the user knows which properties the API uses.
First the developer can focus on testing, then shape the Api through customization.
Another concept widely used today is having the API defined even before its implementation.
With this framework it is possible to import an Open Api Spec. It creates the methods structure (spec) automatically, missing only their implementation.
For Api's governance, it is also recommended to use IAM together.
In addition to having multiple plugins, IAM can quickly couple to APIs through the OAS standard.
apiPub offers additional tracing for APIs (see demo video)
Intersystems Open Exchange: https://openexchange.intersystems.com/?search=apiPub
Complete documentation: https://github.com/devecchijr/apiPub