liminfo

AsyncAPI Reference

Free reference guide: AsyncAPI Reference

25 results

About AsyncAPI Reference

The AsyncAPI Reference is a searchable cheat sheet for AsyncAPI 3.0, the open-source specification for event-driven APIs and message-based architectures. It covers six core sections: Channels (asyncapi version declaration, channel definitions with address, operations with send/receive action, and dynamic address parameters), Messages (message structure with contentType, headers with correlationId and timestamp, correlationId location expressions, and reusable messageTraits), Servers (broker server definitions with host and protocol, supported protocols: Kafka, AMQP/RabbitMQ, MQTT, WebSocket, NATS), Bindings (protocol-specific configuration for Kafka topics/partitions/replicas, AMQP queues with durable/exclusive flags, MQTT QoS/retain/clientId, WebSocket method/query), Schemas (JSON Schema-based payload definitions with required fields, $ref for component reuse, oneOf/anyOf for polymorphic messages, enum constraints), and Security (securitySchemes with apiKey, OAuth2 clientCredentials flow with scopes, userPassword, X509 certificate, SASL/SCRAM-SHA-256 for Kafka, and channel-level security).

AsyncAPI is used by platform engineers, backend developers, and API architects who design and document event-driven systems. It is the async equivalent of OpenAPI — where OpenAPI documents REST APIs with request/response patterns, AsyncAPI documents message broker APIs with publish/subscribe and request/reply patterns across protocols like Kafka, RabbitMQ, MQTT, and WebSocket. Major organizations use AsyncAPI to generate documentation, client SDKs, server stubs, and validation schemas from a single spec file.

The AsyncAPI 3.0 specification introduced a cleaner separation between channels (where messages flow) and operations (what actions happen), making the spec more protocol-agnostic. The binding system allows protocol-specific configuration without polluting the core channel/message definitions. This reference organizes all these concepts into six intuitive categories, with copy-ready YAML examples for each entry. All content runs in your browser with no registration required and full dark mode support.

Key Features

  • Channel definitions: address, channel-level parameters with dynamic {userId} path segments, and message references
  • Operations: send/receive action types with channel and message $refs for AsyncAPI 3.0 operation model
  • Message structure: contentType, name/title metadata, payload $ref, headers with correlationId and timestamp
  • Message traits: reusable commonHeaders with traceId for DRY message definitions across multiple channels
  • Server bindings: Kafka (topic, partitions, replicas, key schema), AMQP (queue name, durable, exclusive), MQTT (QoS, retain, clientId), WebSocket (method, query parameters)
  • JSON Schema payloads: required arrays, property types, format constraints (email, date-time), $ref reuse, oneOf/anyOf for polymorphic event types, enum values
  • Security schemes: apiKey (user/password/cookie), OAuth2 clientCredentials with scopes, userPassword, X509 client certificate, SASL scramSha256 for Kafka
  • Channel-level and server-level security application with $ref to named securitySchemes components

Frequently Asked Questions

What is AsyncAPI and how does it differ from OpenAPI?

AsyncAPI is a specification for documenting event-driven APIs that use message brokers and pub/sub patterns. OpenAPI documents synchronous REST APIs with HTTP request/response cycles. AsyncAPI documents asynchronous APIs where producers publish messages to channels (Kafka topics, AMQP queues, MQTT topics) and consumers subscribe to receive them. AsyncAPI supports Kafka, RabbitMQ/AMQP, MQTT, WebSocket, NATS, and other protocols via its binding system.

What changed in AsyncAPI 3.0 regarding channels and operations?

In AsyncAPI 3.0, channels and operations are now separate top-level objects. Channels define where messages flow (address and message schemas), while operations define what actions occur (send or receive) on those channels. This decoupling makes the spec more protocol-agnostic and allows an operation to specify exactly which messages it handles via an explicit message array of $refs.

How do I define a Kafka topic with partitions and replication in AsyncAPI?

Add a "bindings.kafka" block to your channel definition. Specify "topic" for the Kafka topic name, "partitions" for the partition count, "replicas" for the replication factor, and optionally a "key" schema defining the message key type. These Kafka-specific settings live in the binding and do not affect the general channel/message structure.

What is correlationId and why is it important in AsyncAPI?

correlationId links a request message to its corresponding response message in request/reply patterns. In AsyncAPI, you define the correlationId location using a runtime expression like "$message.header#/correlationId" which points to the correlationId field in the message header. This allows systems to match async responses to their originating requests, which is essential for patterns like async RPC over Kafka.

How do I reuse message definitions across multiple channels with traits?

Define common header structures in "components.messageTraits" — for example, a commonHeaders trait with a traceId property for distributed tracing. Then reference the trait in individual message definitions using "traits: [{$ref: '#/components/messageTraits/commonHeaders'}]". The trait properties are merged into the message definition, avoiding duplication across many message definitions.

How does AsyncAPI handle OAuth2 security for event-driven APIs?

Define an oauth2 security scheme in components.securitySchemes with the appropriate flow type (e.g., clientCredentials for service-to-service). Specify the tokenUrl and define scopes with descriptions. Apply security to servers with "security: [{$ref: '#/components/securitySchemes/oauth2'}]", or to specific channels for channel-level access control. SASL scramSha256 is used for Kafka broker authentication.

What are AsyncAPI bindings and when do I need them?

Bindings provide protocol-specific configuration that extends the generic channel or message definition. They are needed when deploying to a specific broker: Kafka bindings set topic name, partition count, and replication factor; AMQP bindings configure queue durability and exclusivity; MQTT bindings set QoS level and retain flag; WebSocket bindings specify the HTTP upgrade method and query parameters. Bindings keep protocol details out of the core spec while making it deployable.

How do I document a polymorphic event where the payload can be one of several message types?

Use JSON Schema's "oneOf" or "anyOf" in the payload definition, with each option being a $ref to a specific message schema in components.schemas. For example, an OrderEvent channel might have a payload with oneOf: OrderCreated and OrderCancelled schemas. You can also use the AsyncAPI 3.0 operation's "messages" array to explicitly list which message types an operation handles.