AsyncAPI: Documenting Event-Driven APIs

Q: Can AsyncAPI use Avro or Protobuf schemas?

Yes. Message payloads can specify a schemaFormat for Avro, Protobuf, or other formats, including references to schemas stored in a schema registry.

AsyncAPI

HTTP APIs have OpenAPI: a machine-readable contract from which teams generate documentation, clients, mocks, and tests. Event-driven systems — services publishing to Kafka topics, IoT devices on MQTT, real-time features over WebSockets — historically had nothing comparable. Topic names lived in wiki pages, payload formats lived in producer code, and consumers discovered breaking changes in production.

AsyncAPI fills that gap. It is an open specification, hosted by the Linux Foundation, for describing message-driven APIs: which servers (brokers) exist, which channels (topics, queues, routing keys) carry which messages, what each message's payload looks like, and which operations an application performs — sending or receiving. The same document drives documentation, code generation, validation, and contract checks.

TL;DR

AsyncAPI describes message-driven APIs the way OpenAPI describes HTTP APIs.
A document defines servers, channels, operations (send or receive), and messages with payload and header schemas.
AsyncAPI 3.0 separates channels from operations, making request-reply and reuse clearer.
Payloads use JSON Schema by default, or Avro and Protobuf via schemaFormat.
Bindings capture protocol details for Kafka, AMQP, MQTT, WebSockets, NATS, and others.
Validate and lint documents in CI, generate docs and code, and check compatibility before publishing changes.

Quick Example

An AsyncAPI 3.0 document for an orders service that publishes an OrderPlaced event to Kafka:

Core Concepts

Document Structure

An AsyncAPI document describes one application's view: the same Kafka topic appears as send in the producer's document and receive in each consumer's document.

Messages and Schemas

A message has a payload schema, optional headers, a content type, and metadata such as a name, summary, examples, and correlation ID location. Payloads default to an AsyncAPI-flavored JSON Schema; schemaFormat allows Avro, Protobuf, or other formats, so documents can reference schemas already registered in a schema registry. See JSON Schema and Protocol Buffers.

Channels and Parameters

A channel's address can contain parameters — for example devices/{deviceId}/telemetry for MQTT — with schemas for each parameter. Channel-level bindings describe protocol settings such as Kafka partitions and retention, or AMQP exchange types.

Bindings

Bindings capture what generic fields cannot: Kafka message keys and consumer groups, AMQP exchanges and routing keys, MQTT QoS and retain flags, WebSocket handshake details, HTTP methods for webhooks. They make the document precise enough for code generation and testing.

AsyncAPI 3.0 Changes

Version 3.0 decoupled operations from channels, introduced explicit request-reply, made channel addresses separate from channel IDs, and improved reuse through references. Version 2.x documents remain common; the AsyncAPI converter can migrate them.

Tooling

Contracts and Evolution

Message contracts change as products evolve, and producers and consumers deploy independently. Treat the AsyncAPI document as the contract:

Version the document and include a version in channel addresses or message names for breaking changes (orders.order-placed.v2).
Diff documents in CI (asyncapi diff) and fail on breaking changes to published messages.
Enforce compatibility in the schema registry at publish time.
Validate payloads in producer tests against the documented schema.

See Event Schema Evolution and Data Contracts and Schema Evolution.

Best Practices

Document Each Application's Perspective

Write one document per service describing what it sends and receives. Aggregated catalogs can combine them into a system-wide view.

Keep Documents Next to Code

Store AsyncAPI files in the service repository, review changes with code, and publish rendered documentation from CI.

Reuse Schemas From the Source of Truth

Reference Avro or Protobuf schemas already in a registry, or generate JSON Schema from code, rather than maintaining divergent copies.

Include Examples and Semantics

Describe when a message is sent, ordering and delivery guarantees, keys, and idempotency expectations — the information consumers most often lack.

Common Mistakes

Documentation That Drifts From Reality

Describing Only the Payload

Breaking Changes Without a New Version

FAQ

What is AsyncAPI?

An open specification for describing event-driven and message-based APIs — brokers, channels, operations, and message formats — in a machine-readable document used for documentation, code generation, and validation.

How is AsyncAPI different from OpenAPI?

OpenAPI describes request-response HTTP APIs: paths, methods, and responses. AsyncAPI describes asynchronous messaging: channels on brokers, messages sent and received, and protocol-specific bindings. They share ideas and can reference the same schemas.

Which protocols does AsyncAPI support?

Many, including Kafka, AMQP (RabbitMQ), MQTT, WebSockets, NATS, Redis, Amazon SNS and SQS, Google Pub/Sub, and HTTP for webhooks, with protocol-specific bindings.

Can AsyncAPI use Avro or Protobuf schemas?

Yes. Message payloads can specify a schemaFormat for Avro, Protobuf, or other formats, including references to schemas stored in a schema registry.

Should I use AsyncAPI 2 or 3?

Use 3.0 for new documents: it separates operations from channels and models request-reply explicitly. Existing 2.x documents can be converted with AsyncAPI tooling.