Insight

Patrycja Rodak

4 min. read

Using AsyncAPI with MuleSoft: what, why & how

AsyncAPI x MuleSoft. What is it? What are the advantages? And how does it work? In this blogpost, we dive into the world of AsyncAPI with MuleSoft, using a concrete example.

What is AsyncAPI?

AsyncAPI is an open-source specification that describes asynchronous APIs and Event-Driven Architecture. It got inspired by well-known OpenAPI Specification and it resembles its structure and ease of use, but while OpenAPI focuses on synchronous (request-response) communication, AsyncAPI is designed for systems where communication happens asynchronously. More information and the documentation can be found here.

AsyncAPI support in MuleSoft

AsyncAPI integration with MuleSoft offers many advantages for building event-driven architectures.

It brings a clear and standardised way to document and design asynchronous APIs. With AsyncAPI in MuleSoft, developers can ensure that their APIs follow consistent structures by defining reusable components, like schemas and messages, with functionalities similar to those already available for RAML and OAS.

AsyncAPI specifications can be designed in Anypoint Design Center using familiar tools. These specs can be validated through Anypoint API Governance, ensuring they meet company standards and best practices. Once ready, they can be published to Anypoint Exchange, making them easy to share and reuse across teams. Consumers can also view these specs through Anypoint API Community Manager and Experience Hub, improving their accessibility.

AsyncAPI integration also makes implementation easier. Developers can scaffold flows directly from the specification in Anypoint Studio or Code Builder. This automatically generates flows and pre-configures connectors, saving time and ensuring the project is well-structured. However, this functionality is currently only available in open beta support, which needs to be enabled by the Anypoint Platform Organisation Admin and the required minimum Mule runtime is 4.6. As of today, message brokers that are supported by APIKit for AsyncAPI are Kafka, Anypoint MQ, Salesforce platform events, and Solace PubSub+.

An AsyncAPI x MuleSoft example

Designing an AsyncAPI specification

Let’s start with a simple example of an asynchronous API, which purpose is handling creation, update and deletion of user accounts.

AsyncAPI example

The first line, asyncapi declares the version of the specification. As of now, Anypoint Platform supports versions 2.0 and 2.6, while the newest one for AsyncAPI is 3.0. Next, we have an info node, which defines the metadata of the specification, like title, version, description, licenses and contact information. Line 10 – defaultContentType – is not required, but can be added as a good practice to define the media-type in the specification.

AsyncAPI example - servers

In the servers field we define connection information about the message brokers, such as protocol, host, port, security and pathname. In this example we use Kafka as a message broker.

AnsyncAPI example - channels

The field channels represents the communication paths or topics through which messages are either published or subscribed to, with fields like address, message and operations. It resembles resources and methods but for RESTful APIs.

AsyncAPI example - components

The components field includes reusable definitions for messages, schemas, security schemes, and other objects that may be referenced throughout the specification. These components can then be referenced multiple times in different sections of the specification.

Publishing to Exchange

After designing an AsyncAPI specification, we can publish it as an asset to Exchange, just the same way as we do with RAML and OAS. The published asset then looks like this:

AsyncAPI example - published asset

Scaffolding the flows in Studio

Once the Beta version is enabled, we can scaffold the flows within the project. This process is similar to working with any other specification: we simply add the AsyncAPI specification as a module to the project. Doing so generates two key configuration files: the global file and the main file, which contains the auto-generated flows. These flows include message listener components with servers and channels added according to the specification. The publishing operation needs to be manually added as we continue implementing the event-driven logic.

Flows

In the global file, beside the APIKit for AsyncAPI, we also get pre-configured message broker connectors, Kafka producer and Kafka listener in this case.

Message broker connectors

Scaffolding also adds a dev-properties file to the project, which we can find in src/main/resources path, in which we can further add our environment specific key values.

In a nutshell

Overall, the generated project follows best practices in terms of structure and naming conventions, which is convenient if we are not using any templates on our project. The APIKit’s Message Listener component is a useful addition but remains quite basic, as settings like Ack mode or Poll timeout cannot yet be configured. However, AsyncAPI’s integration with MuleSoft provides a solid foundation for building event-driven architectures within the MuleSoft ecosystem. Despite some limitations in the current Beta version, future iterations are likely to bring more flexibility and robustness.

Interested in a collaboration?