AsyncAPI Operations — Complete Guide

In this tutorial, you will learn about AsyncAPI Operations. We cover key concepts, practical examples, and best practices to help you master this topic.

Operations in AsyncAPI define how messages flow through channels. Each operation represents either a publish (server sends) or subscribe (server receives) action, with configurable routing, binding, and message handling.

What You'll Learn

• Operation structure and semantics
• Operation ID and its importance
• Message routing within operations
• Operation-level bindings
• Operation traits for reuse

Why It Matters

Operations define the actual behavior of your API. Correct operation definitions enable accurate Code Generation, documentation, and automated testing of event-driven systems.

Real-World Use

A notification service defines operations for each notification channel. The sendEmail operation subscribes to the notification/email channel, applies Rate Limiting, and routes to the appropriate email provider.

Flow Chart

flowchart LR
    A[Channel] --> B{Operation Type}
    B -->|Publish| C[Server sends message]
    B -->|Subscribe| D[Server receives message]
    C --> E[Operation ID: emitEvent]
    D --> F[Operation ID: onEvent]
    E --> G[Message Routing]
    F --> G
    G --> H[Consumer/Producer]

Code Examples

Example 1: Publish and Subscribe Operations

channels:
  order/events:
    publish:
      operationId: emitOrderEvent
      summary: Emit order lifecycle events
      description: Service publishes order events
      tags:
        - name: orders
        - name: events
      message:
        $ref: '#/components/messages/OrderEvent'
      bindings:
        kafka:
          clientId: order-producer

    subscribe:
      operationId: onOrderAcknowledged
      summary: Receive order acknowledgments
      description: Service receives ACK events
      message:
        $ref: '#/components/messages/OrderAcknowledged'
      traits:
        - $ref: '#/components/operationTraits/retryConfig'

Expected output: Two operations on the same channel with different directions, appropriate operation IDs, and binding configurations.

Example 2: Operation with Multiple Messages

channels:
  notification/events:
    subscribe:
      operationId: processNotification
      summary: Process incoming notifications
      description: >
        Handles multiple notification types
        routed based on message headers
      message:
        oneOf:
          - $ref: '#/components/messages/EmailNotification'
          - $ref: '#/components/messages/SMSNotification'
          - $ref: '#/components/messages/PushNotification'
      traits:
        - $ref: '#/components/operationTraits/rateLimiting'
        - $ref: '#/components/operationTraits/retryConfig'

components:
  operationTraits:
    rateLimiting:
      bindings:
        kafka:
          throttle: 100
      description: Apply rate limiting to operations
    retryConfig:
      description: Retry configuration
      externalDocs:
        url: https://docs.example.com/retry-policy

Expected output: A subscribe operation that handles three different message types with shared operation traits for rate limiting and retry.

Example 3: Operation with Action Field

channels:
  sensor/{sensorId}/commands:
    parameters:
      sensorId:
        schema:
          type: string
    subscribe:
      operationId: processSensorCommand
      summary: Process commands for specific sensor
      message:
        payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - calibrate
                - reboot
                - updateFirmware
                - setInterval
            parameters:
              type: object
      traits:
        - $ref: '#/components/operationTraits/validateCommand'

  sensor/{sensorId}/telemetry:
    publish:
      operationId: emitSensorTelemetry
      summary: Emit sensor readings
      message:
        payload:
          type: object
          properties:
            temperature:
              type: number
            humidity:
              type: number
            pressure:
              type: number

Expected output: Parameterized channel operations for sending commands to and receiving telemetry from IoT sensors.

Common Mistakes

Practice Questions

1. What is the purpose of operationId in AsyncAPI?
2. How do you define an operation that handles multiple message types?
3. What operation traits can you define and how are they reused?
4. Can a channel have multiple publish or subscribe operations?
5. How do operations relate to code generation?

Challenge

Design operations for a real-time analytics pipeline. Include operations for ingesting raw events (subscribe), publishing aggregated metrics (publish), and handling backpressure signals (subscribe with priority). Document operation-level error handling and retry policies.

FAQ

Mini Project

Design operations for a ride-sharing platform. Include operations for: driver sends location update (publish), passenger requests ride (publish), system assigns driver (subscribe), driver accepts/rejects ride (publish), and payment processed notification (subscribe).

What's Next

Learn about protocol bindings in AsyncAPI