Skip to content

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 (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 POST request 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., 200 OK, 404 Not Found, 500 Internal Server Error).

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 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.

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'

A request/response API endpoint can be modeled as a subscribe operation with a reply.

  • The operation binding defines the request method (GET) and any query parameters.
  • The reply section points to a message whose bindings define the expected statusCode and response headers.
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.

VersionWhat changedPages
0.3.0latest

Message binding adds statusCode.

server, channel, operation, message
0.2.0

Operation binding removes is, type.

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

FieldTypeDescription
methodstring
GETPUTPOSTPATCHDELETEHEADOPTIONSCONNECTTRACE
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'
querySchema ObjectA 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

FieldTypeDescription
headersSchema ObjectA Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type 'object' and have a 'properties' key
statusCodenumberThe 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.

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.