HTTP Bindings
While AsyncAPI is primarily designed for asynchronous, event-driven architectures, many systems include synchronous, request/response interactions over HTTP. This is especially common for systems that use webhooks to deliver events. The HTTP bindings for AsyncAPI provide a standardized way to describe these interactions.
HTTP Protocol Overview
Section titled “HTTP Protocol Overview”HTTP (Hypertext Transfer Protocol) is the foundation of data communication for the World Wide Web. It is a client-server protocol where requests are initiated by the recipient, usually a Web browser.
Key concepts for these bindings include:
- Webhooks: A common pattern where a server sends an HTTP
POSTrequest to a client-specified URL to notify it of an event. This is a way to achieve “push” behavior over HTTP. - Request/Response: The classic synchronous pattern where a client sends a request and waits for a response from the server.
- Methods: The action to be performed (e.g.,
GET,POST,PUT,DELETE). - Headers: Metadata sent with a request or response.
- Query Parameters: Data sent in the URL to specify resources or options.
- Status Codes: A three-digit code indicating the result of a request (e.g.,
200OK,404Not Found,500Internal Server Error).
AsyncAPI HTTP Bindings
Section titled “AsyncAPI HTTP Bindings”The HTTP bindings allow you to map AsyncAPI concepts to synchronous HTTP interactions, making it possible to document your entire architecture, both async and sync, in one place.
Binding Types
Section titled “Binding Types”| Binding Type | Purpose | Description |
|---|---|---|
| Channel Binding | (Placeholder) | Marks the channel as an HTTP endpoint. |
| Operation Binding | Request Configuration | Defines the HTTP method (GET, POST, etc.) and the schema for URL query parameters. |
| Message Binding | Header & Status Code Configuration | Defines the schema for HTTP headers and the expected HTTP status code for a response message. |
| Server Binding | (Placeholder) | Marks the server as an HTTP-based server. |
Core HTTP Concepts in AsyncAPI
Section titled “Core HTTP Concepts in AsyncAPI”Defining a Webhook
Section titled “Defining a Webhook”A webhook can be modeled as a publish operation on a channel. The operation binding specifies the method (usually POST), and the message binding defines the headers and payload of the webhook.
operations: receiveUserSignup: action: send channel: $ref: '#/channels/userSignupWebhook' bindings: http: method: 'POST'Defining a Request/Response Endpoint
Section titled “Defining a Request/Response Endpoint”A request/response API endpoint can be modeled as a subscribe operation with a reply.
- The
operationbinding defines the request method (GET) and anyqueryparameters. - The
replysection points to amessagewhosebindingsdefine the expectedstatusCodeand responseheaders.
operations: getUserById: action: receive channel: $ref: '#/channels/users' bindings: http: method: 'GET' query: type: object properties: id: type: string reply: messages: - $ref: '#/messages/userResponse'Versions and changes
Generated from the binding JSON Schemas: every field each version added or removed.
| Version | What changed | Pages |
|---|---|---|
| 0.3.0latest | Message binding adds | server, channel, operation, message |
| 0.2.0 | Operation binding removes | server, channel, operation, message |
| 0.1.0 | First version: operation binding, message binding. | server, channel, operation, message |
Fields in version 0.3.0
Operation binding
| Field | Type | Description |
|---|---|---|
method | stringGETPUTPOSTPATCHDELETEHEADOPTIONSCONNECTTRACE | When 'type' is 'request', this is the HTTP method, otherwise it MUST be ignored. Its value MUST be one of 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', and 'TRACE' |
query | Schema Object | A Schema object containing the definitions for each query parameter. This schema MUST be of type 'object' and have a properties key |
Operation binding 0.3.0: examples and details
Message binding
| Field | Type | Description |
|---|---|---|
headers | Schema Object | A Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type 'object' and have a 'properties' key |
statusCode | number | The HTTP response status code according to RFC 9110. `statusCode` is only relevant for messages referenced by the Operation Reply Object, as it defines the status code for the response. In all other cases, this value can be safely ignored |
Message binding 0.3.0: examples and details
Validate with JSON Schema
Point your editor, CI or AI agent at these schemas to validate the HTTP bindings of version 0.3.0. They come from the AsyncAPI JSON Schema registry.
- Server binding:
https://schemas.asyncapi.pavelon.dev/draft-07/bindings/http/0.3.0/server - Channel binding:
https://schemas.asyncapi.pavelon.dev/draft-07/bindings/http/0.3.0/channel - Operation binding:
https://schemas.asyncapi.pavelon.dev/draft-07/bindings/http/0.3.0/operation - Message binding:
https://schemas.asyncapi.pavelon.dev/draft-07/bindings/http/0.3.0/message
Questions
How do I describe an HTTP request in AsyncAPI?
With the HTTP operation binding: method and a query schema. The message binding adds headers and, since 0.3.0, statusCode for responses.
What happened to type: request in the HTTP binding?
Version 0.2.0 removed the operation type field. In AsyncAPI 3 the operation action and reply say who sends and who answers.