liveBook · Manning

AsyncAPI

As explained in Microservices Patterns, Second Edition

AsyncAPI is a machine-readable specification for defining asynchronous messaging APIs, including channels, messages, operations, and message schemas.

AsyncAPI is a machine-readable interface definition language for asynchronous messaging APIs. It describes both message content and how a service communicates through a messaging system; it applies beyond event-driven architectures. Its contract can support documentation, validation, code generation, and compatibility checking. section 8.3.5

An AsyncAPI document defines three core parts:

  • Channels: the message channels a service uses. section 8.3.5
  • Messages: the types and schemas of messages exchanged over those channels. section 8.3.5
  • Operations: how the service participates in message flow, including sending or receiving. section 8.3.5

Use AsyncAPI when teams need a precise, shareable contract for a messaging API. It is useful for consistent tooling across services, though it is not as universal as OpenAPI is for REST APIs. section 8.3.5 section 8.4

Listing 8.3 An excerpt from an AsyncAPI document that defines a service publishing events such as CustomerCreatedEvent to the com.example.Customer channel.
channels:
  com.example.Customer:
    address: com.example.Customer
    messages:
      com.example.CustomerCreatedEvent:
        $ref: "#/components/messages/com.example.CustomerCreatedEvent"
    ...
messages:
    com.example.CustomerCreatedEvent:
      headers:
        $ref: "#/components/schemas/HeadersNotDocumented"
      payload:
        schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
        schema:
          $ref: "#/components/schemas/com.example.CustomerCreatedEvent"
      name: com.example.CustomerCreatedEvent
      title: com.example.CustomerCreatedEvent
    ...
components:
  schemas:
   com.example.CustomerCreatedEvent:
      title: CustomerCreatedEvent
      type: object
      properties:
        id:
          type: string
      examples:
        - id: string

operations:
  io.eventuate.exampleapp.events.publisher.CustomerEventPublisherImpl:
    action: send
    channel:
      $ref: "#/channels/com.example.Customer"
    messages:
      - $ref: "#/channels/com.example.Customer/messages/com.example.CustomerCreatedEvent"

The YAML excerpt shows a service publishing CustomerCreatedEvent on the com.example.Customer channel and referring to a schema for its payload. section 8.3.5

How Microservices Patterns, Second Edition covers it

How deep it goes
Specifies channels, message types, flow direction, and schemas, while runtime behavior such as latency and availability is described separately.
Examples
Uses a YAML customer-event document that publishes CustomerCreatedEvent on com.example.Customer.
What you can do after
Apply AsyncAPI to define a service’s channels, message flow, exchanged messages, and schemas.
How it connects
Connects IDLs with OpenAPI, JSON Schema, Protocol Buffers, Avro, code generation, validation, and compatibility checking.

Also explained in

Compare how 2 books explain AsyncAPI →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.