Last Updated on 14/02/2022 by Patryk Bandurski
We are used to designing and exposing REST APIs using Design Center and Anypoint Exchange. MuleSoft is one of the leading middleware vendors that introduced the complete design life cycle. It helped a lot as the majority of the APIs are RESTs. On the other hand, we have event-driven APIs using queues, streams, sockets. So far, we did not have a consistent way to publish such APIs. Fortunately, MuleSoft is evolving, some time ago was added support for Async API in Design Center and Anypoint Exchange. Today I focus on the advantages of the Async API solution and a brief introduction to it.
What is Async API?
Async API is based on an Open API specification that defines interfaces for asynchronous APIs. The specification is protocol-agnostic so that you can work with Web Sockets, Kafka, HTTP streams, etc.
You can find complete documentation on the AsyncAPI web page. I encourage you to visit the page. You can play with the examples online and read the docs.
Advantages of Async API
- Simillar to Open API and RAML specifications
- Known specification
- Human readable
- Machine readable
- Protocol-agnostic (
- Support in Design Center and Anypoint Exchange
Example Async API for Payment Service
AsyncAPI has easily understood sections. In my example below, I have
- info (line 2) with basic descriptive information about my API
- servers (line 6) with server details to use by consumers/publishers
- channels (line 15) with queues/topics exposed by API
- components (line 29) with data types, security schemats etc
asyncapi: 2.0.0 info: title: Payment Service version: v1 description: This service is in charge of processing payments servers: test: url: test-broker.ambassadorpatryk.com protocol: jms description: This is JMS broker dedicated to test environments such as DEV/SIT prod: url: broker.ambassadorpatryk.com protocol: jms description: This is JMS broker dedicated to production channels: payment/failed: subscribe: message: $ref: '#/components/messages/PaymentFailed' payment/approved: subscribe: message: $ref: '#/components/messages/PaymentApproved' payment: publish: summary: Create new payment message: $ref: '#/components/messages/Payment' components: messages: Payment: payload: type: object properties: paymentId: type: string description: Payment ID amount: type: number description: Payment amount description: type: string PaymentApproved: payload: type: object properties: paymentId: type: string description: Payment ID PaymentFailed: payload: type: object properties: paymentId: type: string description: Payment ID reason: type: string description: Payment failure resaon
Payment Service is exposing three queues. In the servers‘ part, you can see connectivity details for test and prod environments. In the channels section, we have
- payment/failed – subscribe – this is a queue that user can subscribe to, to receive event notifications about failed payments
- payment/approved – subscribe – this is a queue that user can subscribe to, to receive event notification about approved payments
- payment – publish – this is queue that user can push message to initiate payment process
With each channel, we have associated data type like PaymentApproved. It gives consumers clear information on what structure is expected.
MuleSoft added support to design Async API in Design Center and publish it to Anypoint Exchange. Experience is very similar to working with RAML specifications. You only need to pick New AsyncAPI from the drop-down while creating a new Project in Design Center.
Our Application Network can grow even bigger by introducing event-driven APIs. It is consistent with the current approach, so the users familiar with REST APIs on Anypoint Exchange will easily understand event-driver APIs.
In my opinion, this is another next step that I appreciate. I hope that MuleSoft will develop this feature even more and include something of Router, and enable code scaffolding like with the RAML specification. I keep thumbs up.
Async API is a specification based on Open API but dedicated to describing event-driven APIs. As a result, the learning curve is lower for people having experience with either RAML or Open API specification. You can start nearly straight away writing your own Async APIs.
Anypoint Platform support is limited for now. However, you can create Async API in Design Center and publish it on Anypoint Exchange. I see enormous potential in this, and I think we can expect further development and features that MuleSoft will provide.
2 thoughts on “Async API is a way to describe event-driven APIs”
This article is well written and understood the concept of Asynch .
After this i am trying to generate the flow from RAML in studio but its not generating . did you try try to generate the flow from the above RAML?
thanks for the comment. Regarding the AsyncAPI specifications written in Design Center and published on Anypoint Exchange, there is not yet feature to generate stubs based on async specification. I haven’t seen future plans to develop this, but it would be a great next step if they prepare scaffolding from AsyncAPI specification.