AsyncAPI for event-driven architectures

An industry standard for defining asynchronous APIs for event-driven architecture

⚡ Tl;dr

• AsyncAPI is a standard for describing the communication between services and applications for asynchronous event-driven architectures (EDA).
• AsyncAPI specs allow you to easily generate data models, client libraries, server code and documentation in various languages to speed up the development process.

🚀 Let’s kick-off

You’ve likely heard of the Swagger OpenAPI specification, as it’s widely used in software engineering to describe how systems communicate over REST APIs. However, one of the biggest challenges with Swagger has been describing event-driven systems, as this wasn’t what it was designed to do.

AsyncAPI aims to solve this problem by making it easy to describe communication for bi-directional event-based architectures. This includes asynchronous technologies such as WebSockets, Kafka, RabbitMQ, etc.

💡 Key concepts

AsyncAPI has seven core concepts that are used when writing the definition. They align closely with the terminology and concepts you hear about when discussing event-driven architectures.

1️⃣ Server: Servers represent message brokers that transmit messages between producers and consumers. Their job is to transmit and deliver asynchronous messages between one or more clients.

2️⃣ Producer: Producers are applications that publish messages, usually based on a state change or user action. When messages are published they’re delivered to other entities that subscribe to them.

3️⃣ Consumer: A consumer is an application that subscribes to specific events from a server and reacts to them. They aren’t aware of other producers and consumers involved, only the messages they receive through subscriptions.

4️⃣ Channel: Channels are created by the server and help organize the transmission of messages. They ensure the right messages are routed to the right consumers. You can define channels as a topic, queue, routing, key, path or subject.

5️⃣ Application: An application is one or more services, devices, processes, etc. They should either be a procedure of events, a consumer of events, or both.

6️⃣ Protocol: A protocol is a set of rules for communicating between many applications and/or servers. Examples of protocols that can be used are WebSockets, gRPC, HTTP, Kafka and MQTT.

7️⃣ Message: Messages transmit data from one sender to one or more receivers through a channel and can be defined as an event, query or command. Query and commands can be thought of as instructional messages carrying information, while an event provides details of something that’s already occurred. A payload can be included in messages and is formatted as JSON, XML, binary, etc.

📄 Specification

AsyncAPI started as an adaption of OpenAPI, making most parts of the specification similar. It was created with the intention that users could interchangeably reuse elements in either specification.

The spec can be written as YAML or JSON and is usually checked into source control, either globally or per service/application exposing the interface. Below is a short example spec showing how to define an application that allows consumers to subscribe to a signed-up user.

asyncapi: 2.6.0
info:
  title: Example
  version: 0.1.0
channels:
  user/signedup:
    subscribe:
      message:
        description: An event describing that a user just signed up.
        payload:
          type: object
          additionalProperties: false
          properties:
            fullName:
              type: string
            email:
              type: string
              format: email
            age:
              type: integer
              minimum: 18

The following image from the AsyncAPI website gives a high-level overview of the structure.

🔨 Tools

Studio: Studio allows you to design, validate and visualize your AsyncAPI specs in a web browser. It includes a YAML-based editor and HTML documentation renderer.

Generator: This generates documentation, server and client code from an AsyncAPI specification. There are many official and community-supported templates, including NodeJS, Java, Python, HTML, Markdown, Typescript, Golang, .NET and PHP.

CLI: The CLI tool lets you create and validate AsyncAPI files from your command line. It also supports generating typed models for Typescript, C#, Golang, Java, Javascript, Dart, Rust and Kotlin.

GitHub Action: An official GitHub action that makes it easy to generate HTML documentation from your AsyncAPI spec. You can then deploy it to GitHub pages or similar.

Parser: Easily parse and validate AsyncAPI specs from YAML or JSON. The library also includes Typescript types for manipulating and accessing the properties of your spec.

Modelina: Automatically generate data model types from your AsyncAPI, OpenAPI or JSON schema documents into languages like Java, Typescript, C#, Go, Javascript, Dart, Rust, Python and Kotlin.

🏁 To wrap up

AsyncAPI has been listed in the early adoption phase of the InfoQ Architecture Trends Report for the last 3 years, with adoption from companies like Slack, Salesforce and SAP. They are also part of the Linux Foundation, which is a non-profit that supports leading open-source software projects and standards.

Check out the AsyncAPI site for more info.

Stay chill 🧊