AsyncAPI Specification

The root object of an AsyncAPI document. It contains metadata about the API and references all other components.

• Required Fields: asyncapi (specification version), info (title, version), channels.
• Info Object: Contains title, version, description, and contact/license information.
• Servers Object: Defines the network endpoints (brokers, servers) where the API is available, including protocol (e.g., kafka, mqtt), security schemes, and variables.

Defines the addressable endpoints for messages, analogous to topics, queues, or event names. It is the core routing mechanism.

• Structure: A map where keys are channel names (e.g., user/signedup) and values are Channel Item Objects.
• Channel Item Object: Describes the operations available on that channel (subscribe for receiving, publish for sending) and the messages that flow through it.
• Parameters: Channels can include templated parameters (e.g., user/{userId}/events), defined with a parameters object referencing Schema Objects.

Describes a specific action (publish or subscribe) that an application can perform on a channel.

• Operation Object: Contains an operationId (unique string), a summary, and a description.
• Message Binding: References protocol-specific configuration (e.g., Kafka partition key, MQTT QoS level).
• Traits: Reusable groups of properties for common operation patterns, applied via the traits field to avoid repetition.

Defines the format and semantics of the data packets (events or commands) exchanged over channels.

• Message Object: Describes a message's headers (headers), payload (payload), and correlation ID (correlationId).
• Payload & Headers: Defined using JSON Schema objects, specifying the exact structure of the application data and metadata.
• Examples: Can include sample message objects for documentation.
• Traits: Reusable message definitions (like common error formats) can be defined as components and referenced.

The components object is a container for reusable definitions, promoting consistency and reducing duplication.

• Schemas: Reusable data models defined with JSON Schema Draft 7+, referenced via $ref (e.g., #/components/schemas/User).
• Other Reusables: Can also contain reusable messages, securitySchemes, parameters, and correlationIds.
• External References: Schemas can be loaded from external files or URLs, enabling a modular API design.

Protocol-specific configuration that extends the core, protocol-agnostic AsyncAPI model.

• Purpose: Provides details necessary for implementation with a specific protocol (e.g., AMQP, HTTP, Kafka, MQTT).
• Scope: Bindings can be defined at the server, channel, or operation level.
• Examples:
  • Kafka: Defines partition key, schema registry URL, and consumer group ID.
  • MQTT: Specifies Quality of Service (QoS) level and retain flag.
  • HTTP: Describes the HTTP method and query parameters for a Webhook channel.

A software design paradigm where the flow of the application is determined by events—significant state changes or occurrences. Components (producers) emit events, which are then consumed by other components (consumers) asynchronously.

• Core Principles: Loose coupling, asynchronous communication, and reactivity.
• Enabling Technologies: Message brokers (Kafka, RabbitMQ), event streams, and pub/sub systems.
• AsyncAPI's Role: Provides the formal contract for the events and channels in an EDA, describing the event schema, channel topology, and server endpoints.

An intermediary software module that translates messages from the formal messaging protocol of a sender to the formal messaging protocol of a receiver. It is the runtime infrastructure for asynchronous APIs.

• Primary Functions: Decouples producers from consumers, provides message routing, persistence, and delivery guarantees (at-least-once, exactly-once).
• Common Examples: Apache Kafka (distributed event streaming), RabbitMQ (message queueing), NATS (pub/sub), MQTT brokers (IoT).
• AsyncAPI Integration: An AsyncAPI document's servers section defines how to connect to one or more brokers. The channels map to topics, queues, or streams within the broker.