Message Bindings

Configure protocol-specific settings for WebSocket, MQTT, Kafka, and other protocols

Bindings in AsyncAPI allow you to specify protocol-specific information for servers, channels, operations, and messages. This enables you to provide detailed configuration for different messaging protocols.

asyncapi.yml
1channels:
2 user/notifications:
3 address: user/notifications
4 messages:
5 UserNotification:
6 $ref: '#/components/messages/UserNotification'
7 bindings:
8 ws:
9 method: GET
10 query:
11 type: object
12 properties:
13 token:
14 type: string
15 description: Authentication token

WebSocket bindings

Configure WebSocket-specific settings for real-time communication:

asyncapi.yml
1channels:
2 chat/room:
3 address: chat/room/{roomId}
4 bindings:
5 ws:
6 method: GET
7 headers:
8 type: object
9 properties:
10 Authorization:
11 type: string
12 query:
13 type: object
14 properties:
15 userId:
16 type: string
17 roomId:
18 type: string
19
20operations:
21 sendMessage:
22 action: send
23 channel:
24 $ref: '#/channels/chat~1room'
25 bindings:
26 ws:
27 type: request
28 method: message

MQTT bindings

Configure MQTT-specific settings for IoT and messaging applications:

asyncapi.yml
1channels:
2 device/telemetry:
3 address: device/{deviceId}/telemetry
4 bindings:
5 mqtt:
6 qos: 1
7 retain: true
8 messageExpiryInterval: 3600
9
10servers:
11 mqtt-broker:
12 host: mqtt.example.com
13 protocol: mqtt
14 bindings:
15 mqtt:
16 clientId: device-client
17 cleanSession: false
18 keepAlive: 60
19 will:
20 topic: device/status
21 payload: "offline"
22 qos: 1
23 retain: true

Kafka bindings

Configure Kafka-specific settings for high-throughput event streaming:

asyncapi.yml
1channels:
2 user.events:
3 address: user.events
4 bindings:
5 kafka:
6 topic: user.events
7 partitions: 10
8 replicas: 3
9 topicConfiguration:
10 cleanup.policy: ["delete"]
11 retention.ms: 604800000
12 segment.ms: 86400000
13
14operations:
15 publishUserEvent:
16 action: send
17 channel:
18 $ref: '#/channels/user.events'
19 bindings:
20 kafka:
21 groupId: user-event-processors
22 key:
23 type: string
24 description: User ID for partitioning

Server bindings

Configure protocol-specific server settings:

asyncapi.yml
1servers:
2 websocket-server:
3 host: ws.example.com
4 protocol: wss
5 description: WebSocket server with SSL
6 bindings:
7 ws:
8 headers:
9 type: object
10 properties:
11 X-API-Version:
12 type: string
13 const: "v1"
14
15 kafka-cluster:
16 host: kafka.example.com:9092
17 protocol: kafka
18 bindings:
19 kafka:
20 schemaRegistryUrl: https://schema-registry.example.com
21 schemaRegistryVendor: confluent

Message bindings

Configure how messages are handled by specific protocols:

asyncapi.yml
1components:
2 messages:
3 OrderEvent:
4 name: OrderEvent
5 contentType: application/json
6 payload:
7 $ref: '#/components/schemas/Order'
8 bindings:
9 kafka:
10 key:
11 type: string
12 description: Order ID for consistent partitioning
13 headers:
14 type: object
15 properties:
16 eventType:
17 type: string
18 enum: [created, updated, cancelled]
19 mqtt:
20 qos: 2
21 retain: false

HTTP bindings

For HTTP-based protocols like Server-Sent Events:

asyncapi.yml
1channels:
2 events/stream:
3 address: /events/stream
4 bindings:
5 http:
6 type: response
7 method: GET
8 query:
9 type: object
10 properties:
11 lastEventId:
12 type: string
13 description: Last received event ID for resumption
14
15operations:
16 streamEvents:
17 action: send
18 channel:
19 $ref: '#/channels/events~1stream'
20 bindings:
21 http:
22 type: response
23 statusCode: 200
24 headers:
25 type: object
26 properties:
27 Content-Type:
28 type: string
29 const: text/event-stream

Bindings provide the flexibility to leverage protocol-specific features while maintaining a unified API specification across different transport mechanisms.