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)
Open Exchange Tools for Fast APIs
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.
https://openexchange.intersystems.com/package/IRIS-apiPub
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:
https://openexchange.intersystems.com/package/iris-web-swagger-ui
What is the Open API Specification (OAS)?
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…
Traditional way in to publish API using IRIS
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.
How can we be faster?
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.
Why is the OAS 3.x standard so important?
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.
Using Swagger we will already visualize our API (image above) and call it. This is also very useful for testing.
API customization
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.
In this example we are defining another path for our API and complementing the information for the end user to have a more friendly experience.
Projection Map for Rest API
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 .
Interoperability (Composite APIs)
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.
Spec-first or Api-first Approach
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.
API Governance and Monitoring
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)
Demo
Download & Documentation
Intersystems Open Exchange: https://openexchange.intersystems.com/?search=apiPub
Complete documentation: https://github.com/devecchijr/apiPub
Top comments (0)