Amazon API Gateway · AsyncAPI Specification
Amazon API Gateway WebSocket API
Version 2018-11-29
Amazon API Gateway WebSocket APIs enable real-time two-way communication between clients and backend services. Clients connect via WebSocket protocol and exchange messages through routes that map to Lambda functions, HTTP endpoints, or other AWS services. The gateway manages connection lifecycle including $connect, $disconnect, and $default routes, plus custom routes based on message content.
Channels
connect
The $connect route is invoked when a client first connects to the WebSocket API. This is where authentication and authorization occur. The connection is established only if the integration returns a successful response. Query string parameters and headers from the initial HTTP upgrade request are available to the integration.
disconnect
The $disconnect route is invoked after a client disconnects from the WebSocket API. This route is best-effort and may not be invoked in all cases (e.g., network interruptions). Use this route for cleanup operations such as removing connection records from a database.
default
The $default route is invoked when no other route matches the incoming message. This serves as a fallback handler for messages that do not match any custom route selection expression. It is also used when the route selection expression evaluates to a value that does not match any defined route key.
customRoute
Custom routes are defined by route keys that match values derived from the route selection expression applied to incoming messages. The default route selection expression is $request.body.action, which extracts the action property from the JSON message body to determine routing.
connectionManagement
The @connections endpoint allows backend services to send messages to specific connected clients, retrieve connection information, or disconnect clients. This is accessed via HTTPS POST, GET, or DELETE from the backend.
Messages
ConnectionRequest
WebSocket Connection Request
The initial connection request sent when a client establishes a WebSocket connection. Includes headers, query parameters, and request context from the HTTP upgrade request.
DisconnectionNotice
WebSocket Disconnection Notice
Notification sent when a client disconnects from the WebSocket API, either through a clean close or due to a timeout or error.
DefaultMessage
Default Route Message
A message received on the $default route when no custom route matches the incoming message content.
CustomRouteMessage
Custom Route Message
A message matched to a custom route based on the route selection expression. The message body is passed to the route's integration.
PostToConnectionMessage
Post to Connection
A message sent from the backend to a specific connected WebSocket client via the @connections management API.
ConnectionStatusResponse
Connection Status
Connection information returned when querying the @connections management endpoint for a specific connection ID.
Servers
wss
websocketEndpoint
WebSocket API endpoint. Clients establish persistent connections to this endpoint for real-time bidirectional communication.
https
managementEndpoint
The @connections management endpoint for sending messages to connected WebSocket clients and managing connection state from backend services.