Documenting Events with Async API

Summary: This post explains what the Async API specification is, and how it is used to generate API Reference documentation for events.


Async API is an API specification standard for events. It is used to define and document message driven APIs in a machine and human readable format. It is protocol agnostic, so can work with Kafka, JMS, AMQP, MQTT, WebSockets and more.

Async API is inspired by the Open API Specification. Async API allows us to describe many aspects of our event API including:

  1. The endpoints
  2. Messages that can be sent and received on those endpoints
  3. Authentication methods
  4. Contact information, license and terms of use.

An Events API can be defined using the Async API specification. Because we write Async API specifications in YAML, they are readable by both humans and machines. The format is meant to foster collaboration. This means our devs, product managers, and other non-technical team members should be able to at least update the high level details.

Why use Async API ?

Using the an Async API document to specify our event APIs helps us:

  1. Generate API Reference docs from our Async-API document using open source tools
  2. If required, generate client libraries and testing infrastructure from the Async-API document using freely available open source tools.
  3. Adopt a design-first approach. It allows developers, architects and product managers to collaborate in defining our event API and its messages in YAML and JSON before implementation. This API-first approach is recommended.

The Async API document file structure

An Async API document has the components shown in the diagram below.

Fig. 1 Components of an Async API documentation. Source, Async API.

The Async API specification refers to the different components of the document as objects. Here is a brief description of what some of the top level objects are for.

  1. Info: Provides metadata about the API. For example title, version, licence, terms of service and contact details.
  2. Servers: Provides connection details of servers.
  3. Channels: Information on the available channels and messages on the broker.
    1. Channel Item: Describes the operations available on a single channel.
      1. Operation: Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. For example, an operation might describe a chat application use case where a user sends a text message to a group.
        1. Message: A definition of the message that will be published or received on this channel.
          1. Headers: Message headers are defined here.
          2. Payload: The schema of the message is defined here. Alternatively, to improve readability, this can be a document path reference to a schema of the message in the Components object. The schema is called a Schema Object, and has to conform to the JSON Schema Specification. (Note that this is JSON Schema Specification, not just JSON).
  4. Id: Identifier for the software system the document is defining..
  5. Tags: A list of tags used by the specification with additional metadata. Just like in Open API, you can assign tags to operations. Different tools and libraries can use these tags in different ways – for example, to group related operations.
  6. External Docs: Additional external documentation.
  7. Components: This object holds a set of reusable objects for different aspects of the AsyncAPI specification. For reuse and readability, objects can be defined here are referenced from other sections of the document. For example,
    1. the Message object here in components can hold the full schema definition, and this can be referenced from Operation > Message.
    2. The Security Schemas object defines the security scheme used on the broker. For example, User/Password, X509 certificate, or OAuth2. The Security Schema object is referenced from the Servers object..

The full API Schema specification is documented here. It’s a good reference to use when working on an Async API document.

Further References

  1. The Async API Playground is a visual tool that renders Async API documents as API Reference documents. Useful for playing around to get a feel of Async API, and for design.
  2. The Async API Tutorial.

Leave a Reply