Adding bindings

Bindings in AsyncAPI provide a way to add protocol-specific information to the AsyncAPI documentation. They can be added to different document parts, such as servers, channels, or messages; they specify standard details specific to a particular protocol. The purpose of bindings is to enhance the API's understanding and usage by providing additional context and configuration options for different protocols.

The following diagram highlights the sections where bindings can be implemented:

Server bindings

Server bindings provide protocol-specific information related to the server configuration. For example, if you use Pulsar as your message broker, you can specify the tenant name in the server bindings.

Here is a diagram explaining server bindings:

This diagram shows where server bindings fit into the AsyncAPI document structure.

The next example showcases how to use server bindings to detail protocol-specific configurations for the server:

1servers:
2  production:
3    bindings:
4      pulsar:
5        tenant: contoso
6        bindingVersion: '0.1.0'

The previous document shows how to set up server bindings for a server that is a Pulsar broker.

Channel bindings

Channel bindings are used to specify protocol-specific information for a specific channel. For example, in Kafka, you can specify number of partitions for a given topic.

Here is a diagram explaining where channel bindings fit into the AsyncAPI document structure:

Here is an example of using channel bindings to specify protocol-specific information for a specific channel:

1channels:
2  user-signedup:
3    bindings:
4      kafka:
5        topic: 'my-specific-topic-name'
6        partitions: 20
7        replicas: 3
8        topicConfiguration:
9          cleanup.policy: ["delete", "compact"]
10          retention.ms: 604800000
11          retention.bytes: 1000000000
12          delete.retention.ms: 86400000
13          max.message.bytes: 1048588
14        bindingVersion: '0.4.0'

The previous document shows how to configure channel bindings for a Kafka topic-representative channel.

Message bindings

Message bindings provide protocol-specific information for a specific message. For example, for the AMQP protocol, you can specify the message type in a protocol-specific notation.

Here is a diagram explaining where message bindings fit into the AsyncAPI document structure:

Here is an example of using message bindings to provide protocol-specific information for a specific message:

1channels:
2  userSignup:
3    address: 'user/signup'
4    messages:
5      userSignupMessage:
6        bindings:
7          amqp:
8            contentEncoding: gzip
9            messageType: 'user.signup'
10            bindingVersion: 0.3.0

The previous document shows how to set up message bindings for a message transported using the AMQP protocol.

Operation bindings

Operation bindings allow you to specify protocol-specific information for a specific operation. For example, for MQTT, you can specify the quality of the service for a given operation.

Here is a diagram explaining where operation bindings fit into the AsyncAPI document structure:

Here is an example of using operation bindings to specify protocol-specific information for a specific operation:

1channels:
2  user/signup:
3operations:
4  userSignup:
5    action: receive
6    bindings:
7      mqtt:
8        qos: 2
9        retain: true
10        bindingVersion: 0.2.0

The previous document shows how to set up operation bindings for an operation that describes how an application that uses MQTT as transport, receives the message.

Using bindings helps you enhance the AsyncAPI documentation with protocol-specific details, making it easier to understand and implement the API.