AsyncAPI Servers — Complete Guide

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

Server definitions in AsyncAPI specify the connection points where services communicate. They include protocol details, authentication, and environment-specific configuration for production, staging, and development.

What You'll Learn

• Server structure and required fields
• Protocol configuration for different brokers
• Security scheme integration
• Multiple environment management
• Server-level bindings

Why It Matters

Accurate server definitions ensure that generated clients and documentation connect to the correct endpoints with proper authentication. Misconfigured servers lead to connection failures in production.

Real-World Use

A global e-commerce platform maintains AsyncAPI specs with separate server definitions for development (local RabbitMQ), staging (shared Kafka cluster), and production (multi-region Kafka with SASL authentication).

Flow Chart

flowchart TD
    A[Server Definition] --> B[URL]
    A --> C[Protocol]
    A --> D[Security]
    A --> E[Bindings]
    B --> F[tcp://kafka:9092]
    C --> G[Protocol Version]
    D --> H[Authentication]
    E --> I[Broker-Specific Config]
    H --> J[SASL/SCRAM]
    H --> K[OAuth2]
    H --> L[API Key]

Code Examples

Example 1: Multiple Environment Servers

servers:
  production:
    url: kafka://prod-kafka.example.com:9092
    protocol: kafka
    description: Production Kafka cluster
    authentication:
      - type: scramSha256
        description: SASL/SCRAM authentication
    bindings:
      kafka:
        clientId: order-service-prod
        groupId: order-processors

  staging:
    url: kafka://staging-kafka.example.com:9092
    protocol: kafka
    description: Staging environment
    security:
      - apiKey: []

  development:
    url: mqtt://localhost:1883
    protocol: mqtt
    description: Local MQTT broker for development
    security:
      - anonymous: []

Expected output: Three server definitions for different environments with appropriate protocols and security for each.

Example 2: Server with Multiple Protocol Support

servers:
  primary:
    url: amqp://rabbitmq.example.com:5672
    protocol: amqp
    protocolVersion: '0.9.1'
    description: RabbitMQ primary cluster
    security:
      - userPassword: []
    bindings:
      amqp:
        connectionTimeout: 30000
        heartbeat: 60
        channelMax: 2047
        vhost: production

  fallback:
    url: mqtt://mqtt.example.com:1883
    protocol: mqtt
    protocolVersion: '3.1.1'
    description: MQTT fallback broker
    bindings:
      mqtt:
        clientId: order-service-fallback
        cleanSession: true
        keepAlive: 60

Expected output: Servers supporting different protocols (AMQP, MQTT) with protocol-specific configurations.

Example 3: Server with OAuth2 Security

servers:
  events:
    url: kafka://events.example.com:9092
    protocol: kafka
    security:
      - oauth2: []

components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authentication
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            events.read: Read event streams
            events.write: Publish events
    apiKey:
      type: apiKey
      in: user
      description: API key for header authentication
    userPassword:
      type: userPassword
      description: RabbitMQ username and password

Expected output: A server secured with OAuth2 client credentials flow, with security scheme definitions in components.

Common Mistakes

Practice Questions

1. What are the required fields for a server definition?
2. How do you configure different authentication methods per server?
3. What is the difference between security at the server level vs channel level?
4. How do you manage server configurations across multiple environments?
5. What protocol-specific bindings are available for Kafka servers?

Challenge

Design server definitions for a multi-region event streaming platform. Include three servers (US-East, EU-West, AP-Southeast) with Kafka protocol, SASL/SCRAM authentication, region-specific connection settings, and a fallback MQTT server for disaster recovery.

FAQ

Mini Project

Design server infrastructure for a global IoT platform with MQTT servers in three regions, a Kafka cluster for data processing, and Websocket servers for real-time dashboards. Include security schemes, environment variables, and protocol-specific bindings for each server type.

What's Next

Learn about operations and message routing in AsyncAPI