Add servers

A server often acts as a message broker, managing communication between producers and consumers. However, it can represent different concepts too. To understand this better, please first review our server concepts doc.

Adding and defining servers is important because it specifies how and where connections are made, enabling the sending and receiving of messages.

Unique keys identify the server and contain information about the server's connection details, such as the host, protocol, and authentication.

Here is a diagram of server information with selected fields:

The server is one of the main sections of the AsyncAPI document next to others like info, channels, or operations.

Define servers

Include server definitions in your AsyncAPI document to specify which server a channel or operation connects to. Here is an example of defining a server in AsyncAPI:

1servers:
2  prod:
3    host: test.mosquitto.org
4    protocol: mqtt
5    description: Test MQTT server

The previous example shows a server setup using the MQTT protocol, where messages are sent to or received from the test.mosquitto.org host.

Server reusability

Add server definitions in a single location, such as components.servers, and then refer to them using the $ref keyword for easy reuse.

Here's an example of an AsyncAPI document with two servers referenced from the components section:

1servers:
2  kafka-test:
3    $ref: '#/components/servers/kafka-test'
4  mqtt-test:
5    $ref: '#/components/servers/mqtt-test'
6components:
7  servers:
8    kafka-test:
9      host: my.kafka.pl
10      protocol: kafka-secure
11      description: Test Kafka server
12    mqtt-test:
13      host: test.mosquitto.org
14      protocol: mqtt
15      description: Test MQTT server

In this example, the main servers section lists multiple servers with sharable definitions. You can also store these server definitions separately and use them across various AsyncAPI documents.

Channel only on specific server

Your AsyncAPI document can outline an application that receives messages on a channel from an MQTT server, while sending messages on a different channel via a Kafka server. This setup requires defining two servers, with each channel being exclusive to one server – one channel is only available on the MQTT server and the other only on the Kafka server. The AsyncAPI document describes this by adding a servers array to each channel, containing references to the respective server definitions.

Here's an example of how to add a server reference to a channel:

1servers:
2  kafka-test:
3    host: my.kafka.pl
4    protocol: kafka-secure
5    description: Test Kafka server
6  mqtt-test:
7    host: test.mosquitto.org
8    protocol: mqtt
9    description: Test MQTT server
10channels:
11  myChannel:
12    servers:
13      $ref: "#/servers/mqtt-test"
14    message:
15      $ref: '#/components/messages/myMessage'

In this example, the myChannel channel is only available on the mqtt-test server.