Servers

Define server URLs and protocols to help users connect to your event-driven API.

AsyncAPI allows you to specify one or more server configurations under the servers key.

asyncapi.yml
1servers: 
2  production:
3    host: api.yourcompany.com
4    protocol: wss
5    description: Production WebSocket server
6  staging:
7    host: staging.api.yourcompany.com
8    protocol: wss
9    description: Staging WebSocket server

Specifying servers is valuable for both SDKs and Docs:

  • For SDKs, your users won’t need to manually specify the server URL at client instantiation
  • For Docs, your API playground will automatically connect to the correct server

Protocol support

AsyncAPI supports various protocols for event-driven communication:

asyncapi.yml
1servers: 
2  websocket-server:
3    host: ws.api.yourcompany.com
4    protocol: ws
5    description: WebSocket server for real-time communication
6  mqtt-server:
7    host: mqtt.yourcompany.com
8    protocol: mqtt
9    description: MQTT broker for IoT devices
10  kafka-server:
11    host: kafka.yourcompany.com
12    protocol: kafka
13    description: Kafka cluster for event streaming

Naming your servers

We recommend giving your servers descriptive names to make it clear what each server is for:

asyncapi.yml
1servers: 
2  production:
3    host: api.yourcompany.com
4    protocol: wss
5    description: Production WebSocket server
6  staging:
7    host: staging.api.yourcompany.com
8    protocol: wss
9    description: Staging environment for testing
10  development:
11    host: localhost:8080
12    protocol: ws
13    description: Local development server

Server variables

You can use variables in your server configurations to make them more flexible:

asyncapi.yml
1servers:
2  production:
3    host: '{environment}.api.yourcompany.com'
4    protocol: wss
5    variables:
6      environment:
7        default: prod
8        enum:
9          - prod
10          - staging
11        description: Environment name

Multiple protocols for different channels

If you have different channels that use different protocols, you can specify this in your server configuration:

asyncapi.yml
1servers:
2  websocket-server:
3    host: ws.api.yourcompany.com
4    protocol: wss
5    description: WebSocket server for real-time notifications
6  mqtt-server:
7    host: mqtt.api.yourcompany.com
8    protocol: mqtt
9    description: MQTT broker for IoT device communication
10  kafka-server:
11    host: kafka.api.yourcompany.com
12    protocol: kafka
13    description: Kafka for high-throughput event streaming
14
15channels:
16  user/notifications:
17    servers:
18      - websocket-server
19    address: user/notifications
20    description: Real-time user notifications via WebSocket
21  device/telemetry:
22    servers:
23      - mqtt-server
24    address: device/telemetry
25    description: IoT device telemetry via MQTT

This allows different channels to use the most appropriate protocol for their use case.