Learn how to use the AsyncAPI contract with cloud-native programming language Ballerina to benefit your API development
In the face of rapid growth in the integration space, the IT industry has the potential to move to event-based architecture(EDA). Developers use event-driven microservices to create applications because it is more adaptable and simpler to maintain over time since it is loosely connected to each service. Asynchronous communication is the most commonly used communication among these architectures. Therefore with the rise of this asynchronous paradigm, developers need to govern their system with proper human and machine-readable documentation for code generation. Most of the processes, that Developers apply to their REST APIs nowadays would be applicable to their event-driven/asynchronous APIs too.
AsyncAPI is one of the leading API specifications to govern and document your asynchronous and event-driven APIs inspired by the OpenAPI specification. It is protocol agnostic. It lets developers define the interface of async API. Much like OpenAPI does for REST API.
I expect that most of you are familiar with AsyncAPI, but to whom it is new to have an introduction here.
The AsyncAPI specification adequately covers all of the key elements in between channels, operations and servers that allow a complete representation of the event-driven topology. It is a precise representation of a message-driven ecosystem.
Ballerina AsyncAPI tool
How Ballerina will support your AsyncAPI contract
For giving the uplift to the event-driven ecosystem, The Ballerina platform provides comprehensive support to generate your own AsyncAPI triggers using the Ballerina AsyncAPI tool. It has been available from the Ballerina Swan Lake GA Release onwards.
For a quick overview regarding the tool:
If your hand is with the AsyncAPI contract, you need to do a few simple modifications by adding custom tags starting with `x-ballerina` to your YAML file. The purpose of adding these tags are
- x-ballerina-event-identifier — For the identify the event type of the event when receiving an event from an event source. This can be type or path.
- x-ballerina-event-type — this is for naming the events inside the channel.
Generate the Ballerina source file related to the AsyncAPI triggers and run the below command
bal asyncapi -i <yaml contract>After executing the above command, four ballerina files have been generated under the given location. Files are `data_types.bal`, `service_types.bal`, ` listener.bal` and `dispacther_service.bal` .
- data_types.bal: This file contains all the Ballerina data types extracted from the AsyncAPI definition under the components schema section.
- service_types.bal: This file contains implementation for all the service types relevant to the event API described in the AsyncAPI definition under the channel sections.
- listener.bal: this contains the HTTP listener, which listens to the relevant third-party service. (API providers)
- dispacther_service.bal: this contains the event dispatching logic which is documented in the contract.
Developers can modify the generated file if more information is needed when initializing the listener like secrets, endpoint URLs, tokens, refresh tokens, etc., and update the init function in the listener.bal file.
How to use these generated triggers
- Make sure to place all the generated files inside the ballerina package before running the generated files. (If you want to make the current folder with the ballerina package, run `bal init` inside the folder to make `Ballerina.toml`. )
- Then create another ballerina file naming `service.bal` and place the below ballerina code with your logic implementation.
3. Run the `bal run` inside the folder to execute the service.
Conclusions
In this article, we had a quick look at AsyncAPI specification and How Ballerina can add value to your asyncAPI contract. You can learn more about the Ballerina AsyncAPI tool here. Give a try to use AsyncAPI tool and make your coding life easy. Happy reading… !
Reference
https://www.asyncapi.com/docs/reference/specification/v2.0.0#definitionsChannel
