AsyncAPI for Event-Driven APIs

AsyncAPI does for event-driven systems what OpenAPI does for HTTP: it describes channels (topics/queues), operations (send/receive), messages (payload schemas, headers, correlation IDs) and protocol bindings (Kafka partitions/keys, AMQP exchanges). AsyncAPI 3.0 separates channels from operations, making it clearer who sends and who receives. Generate docs and code, and validate events in CI and at runtime with a schema registry.

OpenAPI vs AsyncAPI

asyncapi: 3.0.0
info: { title: Order Events, version: 1.2.0 }
servers:
  production: { host: kafka.internal:9092, protocol: kafka }
channels:
  orderPaid:
    address: orders.order-paid.v1
    messages:
      orderPaid: { $ref: "#/components/messages/OrderPaid" }
operations:
  publishOrderPaid:
    action: send
    channel: { $ref: "#/channels/orderPaid" }
components:
  messages:
    OrderPaid:
      headers: { type: object, properties: { traceparent: { type: string } } }
      payload:
        type: object
        required: [eventId, orderId, total, occurredAt]
        properties:
          eventId: { type: string, format: uuid }
          orderId: { type: string }
          total: { type: integer, description: Minor units }
          occurredAt: { type: string, format: date-time }
      bindings: { kafka: { key: { type: string, description: orderId } } }

Common pitfalls

• Undocumented events that other teams reverse-engineer.
• Schemas without versioning or compatibility rules.
• Ignoring headers (trace context, correlation IDs).

Key points

• Channels, operations, messages, bindings
• AsyncAPI 3 separates channels and operations
• Pair with a schema registry

Further reading: AsyncAPI 3.0 specification