Servers

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

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

1 servers: 
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

1 servers: 
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

1 servers: 
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

1 servers:
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

1 servers:
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 
15 channels:
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.

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

asyncapi.yml

1 servers: 
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

1 servers: 
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

1 servers: 
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

1 servers:
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

1 servers:
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 
15 channels:
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.

1	servers:
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

1	servers:
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

1	servers:
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