AsyncAPI is a standard for documenting contracts for asynchronous APIs. Let’s say, you connect multiple services via Apache Kafka or RabbitMQ, AsyncAPI is there to provide information about available servers, topics, queues and payload structures. If you already heard about „OpenAPI“ before: AsyncAPI is the counterpart for asynchronous APIs.
The four main concepts in AsyncAPI are Server, Producer, Consumer and Channel.
As I introduced this blog article by mentioning two concrete messaging systems, you might be irritated by the term Server now – at least I was :). The reason for this confusion is that AsyncAPI is not limited to APIs that build on top of messaging systems but also supports client/server models as it is known from WebSockets.
Producers are components which create and send data. Consumers receive and process exactly that data from the server. Channels are a concept of organizing different types of messages into separate units – like directories on a file system.
To get a little bit more concrete, just imagine an online payment service just like PayPal. It has a User Accounts Service which publishes events when users sign up or sign out. A Newsletter Service wants to know both about sign ups and sign outs in order to maintain its own user database. The invoice Service needs to know about sign outs, because this should send back the remaining credits of a user.
AsyncAPI Definition File
AsyncAPI definitions are YAML or JSON files. The top-level sections servers and channels refer to AsyncAPI’s main concepts already mentioned above. The other two terms from the main concepts, Producer and Consumer do not occur in the AsyncAPI document.
asyncapi: 2.5.0 info: title: SuperPay version: '1.0.0' servers: production: url: rabbitmq.superpay.com protocol: amqp description: This is SuperPays central RabbitMQ production deployment. security: - user-password:  channels: signups: bindings: amqp: is: routingKey exchange: name: myExchange type: topic durable: true autoDelete: false bindingVersion: 0.2.0 publish: description: When a user signs up, a message MUST be published on this channel. message: $ref: '#/components/messages/signup-msg' subscribe: message: $ref: '#/components/messages/signup-msg' signouts: publish: message: $ref: '#/components/messages/signout-msg' subscribe: message: $ref: '#/components/messages/signout-msg' components: messages: signup-msg: name: Signup message summary: >- Informs about a new user has signed up in the system. payload: type: object additionalProperties: false properties: id: type: integer fullName: type: string email: type: string format: email age: type: integer minimum: 18 signout-msg: name: Signout message summary: >- Informs about a user signed out the system payload: type: object additionalProperties: false properties: userId: type: integer securitySchemes: user-password: type: userPassword
Components is just a container for re-useable snippets of the definition file. In the example snippet above, I re-used the payload definition for signup messages by referencing it from
How does AsyncAPI integrate protocol-specific concepts?
A client that should consume data from Apache Kafka needs to know the name of the topic that holds the data. In another scenario, it might not be Kafka but RabbitMQ. Now, there are no topics but queues and exchanges, because, although they are both message brokers, the protocols used under the hood are different.
AsyncAPI integrates these protocol/broker-specific data via so-called bindings. Examples for available bindings are AMQP, JMS, Kafka, NATS, Google Pub/Sub, AWS SQS or WebSocket.
Just to get hands dirty as fast as possible, I recommend AsyncAPI Studio (beta). By combining a text editor and a live html documentation generator, it is a good starting point with a low entry barrier to start fiddling with your first AsyncAPI document.
While AsyncAPI Studio might serve as a good starting point, there will rise more advanced requirements when you start using AsyncAPI in your project. The following list contains just a few examples.
- Code-first tools
- Create AsyncAPI Documents via code
- Code Generators
- Generate a html or markdown documentation
- Generate project stubs in several platforms (spring, node, python, Typescript…. )
- Generate just payload data models for your programming language
- Migrates AsyncAPI documents from older to newer versions
More related tools can be found here.
Data Model Generator: Modelina
npm package and can be installed via
npm install @asyncapi/modelina. Similar to AsyncAPI Studio, a handy browser-based instance is available here. Side note: Modelina is not limited to AsyncAPI. OpenAPI and JSON Schema documents are also supported inputs.