AsyncAPI Complete Guide: Event-Driven API Specification

In this tutorial, you'll learn about AsyncAPI: an open-source specification for describing event-driven APIs that brings the same documentation and code generation benefits to message-based systems that OpenAPI brings to REST.

AsyncAPI is an open specification for documenting event-driven APIs using a JSON/YAML format parallel to OpenAPI, enabling automated documentation and code generation for Kafka, MQTT, and WebSocket systems.

What You'll Learn

• AsyncAPI 2.x and 3.x specification structure
• Channels, messages, payloads, and server definitions
• Bindings for Kafka, MQTT, and AMQP
• Code generation with AsyncAPI Generator
• Designing event-driven APIs with confidence

Why AsyncAPI Matters

REST APIs have OpenAPI — a standard format for documentation, code generation, and validation. Event-driven APIs had no equivalent, so teams relied on wiki pages and tribal knowledge. DodaTech's Durga Antivirus Pro uses AsyncAPI to document its threat event stream, enabling SIEM partners to integrate without reverse-engineering binary message formats.

flowchart TB
    subgraph "AsyncAPI Document"
        S["Spec Version\n(asyncapi: 2.6.0)"] --> I["Info: title, version"]
        S --> SV["Servers: URL, protocol"]
        S --> C["Channels: topics/queues"]
        C --> OP["Operations:\npublish / subscribe"]
        OP --> M["Messages:\npayload schema"]
        M --> REF["$ref components\n(reusable schemas)"]
        SV --> SEC["Security Schemes"]
    end
    style S fill:#dbeafe,stroke:#2563eb
    style C fill:#fef3c7,stroke:#d97706
    style M fill:#dcfce7,stroke:#16a34a

AsyncAPI vs OpenAPI

Common Mistakes

1. Confusing Publish and Subscribe Directions

In AsyncAPI, publish means the server sends messages (clients receive). subscribe means the server receives messages (clients send). Always think from the server's perspective.

2. Not Defining Reusable Components

Writing inline schemas for every message leads to duplication. Use $ref to reference reusable components.messages and components.schemas.

3. Ignoring Server Definitions

Without server definitions, your spec is documentation-only. Add protocol, URL, and security to enable tooling to generate working clients.

4. Not Versioning Event Schemas

Message schemas evolve. Use semantic versioning for your AsyncAPI spec and maintain backward-compatible changes.

5. Overlooking Message Headers

Correlation IDs, timestamps, and message types belong in headers, not payloads. Define headers separately in the message object.

Practice Questions

1. What is the difference between publish and subscribe in AsyncAPI?
2. How does AsyncAPI compare to OpenAPI in terms of purpose?
3. What are bindings and why are they important?
4. How do you reference reusable schemas in AsyncAPI?
5. What new features does AsyncAPI 3.0 introduce?

Answers:

1. From the server's perspective: publish means the server publishes messages for clients to receive. subscribe means the server subscribes to messages from clients.
2. OpenAPI describes REST APIs (request-response). AsyncAPI describes event-driven APIs (publish-subscribe). Both use similar structures (YAML/JSON, components, $ref).
3. Bindings provide protocol-specific configuration (Kafka topic settings, MQTT QoS levels, AMQP queue attributes) that generic message schemas cannot Express.
4. Use $ref: '#/components/messages/MessageName' to reference reusable message schemas. Components can include messages, schemas, security schemes, and parameters.
5. AsyncAPI 3.0 introduces operations as first-class citizens, improves reusability with application-level components, and adds better multi-protocol support in a single spec.

Challenge: Write an AsyncAPI spec for DodaTech's threat detection system. Include channels for threat detection events, scan completion events, and system health status. Use a Kafka server with SASL authentication. Define reusable message schemas for threat payloads and scan results.

FAQ

Try It Yourself

# Install AsyncAPI Generator
npm install -g @asyncapi/generator

# Generate HTML docs from a spec
asyncapi generate fromTemplate https://raw.githubusercontent.com/asyncapi/spec/master/examples/simple.yml @asyncapi/html-template -o docs/

# Open docs/index.html in your browser

What's Next