AsyncAPI is a specification, which is used to describe and document message-driven APIs in a machine-readable format for easy development, discovery, and integration. Ballerina Swan Lake supports the AsyncAPI Specification version 2.x.
The Ballerina AsyncAPI tool makes it easy for you to start the development of an event API documented in an AsyncAPI contract in Ballerina by generating a Ballerina service and listener skeletons.
Set up the prerequisites
To run this tutorial, you need the following prerequisites:
- Ballerina 2202.1.0 (Swan Lake) or greater
- A text editor
Prepare the AsyncAPI contract
Before using the tool, there are some modifications that should be made by adding some custom tags to the contract.
This guide uses only a part of the AsyncAPI specification of Slack for the purpose of simplicity.
There are custom tags in this YAML starting with
x-ballerina. It is very important that these tags must be added to the AsyncAPI contract before using the tool. The usage of those tags are as follows.
x-ballerina-event-identifier - When the listener receives an event from the event source (Slack is the event source in this scenario), there should be a way to identify the event type. This includes two parts,
type- Type can be either header or body. In other words, the type of event can be included in the payload either as an HTTP header or as an attribute in the body.
Note: Currently, this tool supports only the body property. Hence, the path is equal to the JSON path of the attribute.
path- Path is equal to the header-name if the type is
header, or the JSON path of the attribute if the type is
Note: Currently, this tool supports only HTTP-based event APIs.
x-ballerina-event-type - This should be there in every event inside the channel. This is the name of the event or the value of the attribute mentioned above for a specific event.
Generate Ballerina services from AsyncAPI contracts
After modifying the AsyncAPI contract, the Ballerina sources can be generated using the commands below.
bal asyncapi [-i | --input] <asyncapi-contract-file-path> [-o | --output] <output-location>
The generated service can be used as a code template to start the service implementation. For example,
bal asyncapi -i hello.yaml
This generates a Ballerina source (i.e., the four Ballerina files below) from the given AsyncAPI definition file.
data_types.bal- contains all the Ballerina data types extracted from the AsyncAPI definition
service_types.bal- contains all the service types relevant to the event API described in the AsyncAPI definition
listener.bal- contains the HTTP listener, which listens to the relevant third-party service
dispacther_service.bal- contains the event dispatching logic
The generated Ballerina sources are written into the same directory from which the command is run. The above command can be run from anywhere on the execution path. It is not mandatory to run it from within a Ballerina package. If you want to generate Ballerina sources to a specific provided output location, you can modify the above command as below.
bal asyncapi -i hello.yaml -o ./output_path
Then, the generated files can be modified according to the custom requirements. When modifying the generated code segments, it is easier to consider the below facts.
- All the incoming requests are received by the resource function in the
dispatcher_service.balfile. Hence, if there is a necessity to add an authentication logic for the incoming calls, that logic can be included there before processing the incoming HTTP request.
- If more information is needed when initializing the listener such as secrets, endpoint URLs, tokens, refresh tokens, etc., update the
initfunction in the
Execute the generated sources
Follow the steps below to execute the generated Ballerina sources.
1. Navigate to the directory in which the generated files exist.
2. Execute the
bal init command.
Info: This generates a
3. Create a new Ballerina file inside the directory (e.g.,
slack_service.bal ) and copy the code below to it.
4. Execute the
bal run command to execute this.
Below are some example libraries generated using the tool.
|Module||AsyncAPI specification||Generated and modified code||Published module|