WebSocket protocol support
Note
This feature is in the Preview stage.
To connect to an API gateway through WebSocket, client applications need to send a GET request to the URI for which integrations are set up as per the OpenAPI specification. Integrations are invoked when the following operations are performed:
x-yc-apigateway-websocket-connect: Open connections.x-yc-apigateway-websocket-message: Send messages through a web socket.x-yc-apigateway-websocket-disconnect: Close a connection.
x-yc-apigateway-websocket-connect operation
The operation is performed when a new connection is established. API Gatewayinvokes an integration when performing the operation. If the integration is invoked successfully, the client gets a response with the 101 Switching Protocol HTTP code, after which a web socket is considered open as per RFC. Otherwise, an integration returns an error.
For each new web socket, a unique connection ID is generated and returned to the client in the X-Yc-Apigateway-Websocket-Connection-Id header. The connection ID is provided when an integration is invoked. To manage an established connection with the API, e.g., send data to the client side or close the connection, save the received ID, for example, to Yandex Managed Service for YDB.
Below, you can find a list of headers that are additionally provided in an HTTP request to the integration:
X-Yc-Apigateway-Websocket-Connection-Id: Connection ID.X-Yc-Apigateway-Websocket-Event-Type: Event type; in our case, it isCONNECT.X-Yc-Apigateway-Websocket-Connected-At: Connection time.
If the Yandex Cloud Functions function is used as an integration, the above websocket details are provided as individual fields within requestContext of a JSON structure of the request to the function.
For this operation, you can set up authorization using a function. If authorization fails, the connection will not be established and the client will get a response with the 401 or 403 HTTP code.
Clients can use the RFC-specified Sec-WebSocket-Protocol header to request sub-protocol support from the API gateway. The API gateway provides this header in an HTTP request to an integration.
This operation is not required. If the operation is not defined in the specification, the 101 Switching Protocol HTTP code is returned by default after connecting to the client. Add integrations to this operation if you need to:
- Implement specific sub-protocols to enable the communication between the client and the API gateway.
- Know when a connection is opened and closed.
- Based on authorization, manage who can and cannot connect using WebSocket.
- Send messages to the client side through the connection managing API.
- Save the connection ID and other details to databases.
x-yc-apigateway-websocket-message operation
The operation is run when a message is sent from the client side. API Gateway invokes an integration when performing the operation. Data from a websocket is provided in the body of an HTTP request to the integration. Text (UTF-8) and RFC-specified binary messages are supported. For text-based data, the Content-Type header gets the application/json value, while for binary data, it gets application/octet-stream. If the Cloud Functions function is used as an integration, the binary message is Base64-encoded; the resulting string value is written to the body field of the JSON structure of the request, while the isBase64Encoded option is set to true.
The body of the integration response is sent to a web socket at the client side as an individual message. If the Content-Type response from the integration has the application/json value or starts with the text/ prefix, a text message is sent. Otherwise, a binary message is transferred.
The message cannot be larger than 128 KB, while the frame cannot be larger than 32 KB. If a message is larger than 32 KB, split it into multiple frames. If a message or frame exceeds the limit, the connection is closed with the 1009 code.
A unique ID is generated for each message. The message ID is provided in a special header when the integration is invoked. The alphabetic message ID order is time-based.
Below, you can find a list of headers that are additionally provided in an HTTP request to the integration:
X-Yc-Apigateway-Websocket-Connection-Id: Connection ID.X-Yc-Apigateway-Websocket-Event-Type: Event type; in our case, it isMESSAGE.X-Yc-Apigateway-Websocket-Message-Id: Message ID.
If a Cloud Functions function is used as an integration, the above message details are provided as individual fields within requestContext of a JSON structure of the request to the function.
This operation is required. Otherwise, the relevant path in the API gateway's OpenAPI specification will not support WebSocket connection.
x-yc-apigateway-websocket-disconnect operation
The operation is run after a connection is closed as per RFC or terminated. The client or API Gateway may decide to close a connection. API Gateway, while running this operation, always tries to invoke an integration; however, the successful run is not guaranteed.
This operation is not required. If you want to do something while closing a connection, such as delete data about it from the database, we recommend doing so in the integration that is invoked when this operation is running.
Below, you can find a list of headers that are additionally provided in an HTTP request to the integration:
X-Yc-Apigateway-Websocket-Connection-Id: Connection ID.X-Yc-Apigateway-Websocket-Event-Type: Event type; in our case, it isDISCONNECT.X-Yc-Apigateway-Websocket-Disconnect-Status-Code: Status code. For the list of all possible codes, see RFC protocol.X-Yc-Apigateway-Websocket-Disconnect-Reason: Text description of the reason for which the connection closed.
If a Cloud Functions function is used as an integration, the above details about a closed connection are provided as individual fields within requestContext of a JSON structure of the request to the function.
Maximum connection lifetime is 60 minutes. A websocket is considered idle if no messages are received through it after 10 minutes. Then the connection closes. You can occasionally send RFC-specified ping frames so that the API gateway considers the connection active and does not close it.
Since the connection can be closed for the reasons mentioned above or others, when writing client apps, it is recommended that you enable automatic reconnection.
Extension specification
Example of a specification with a static response:
/ws:
x-yc-apigateway-websocket-message:
x-yc-apigateway-integration:
type: dummy
content:
'*': Got new message!
http_code: 200
http_headers:
Content-Type: text/plain
Example of a specification with a function call:
/ws:
x-yc-apigateway-websocket-connect:
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95ic**********
tag: "$latest"
service_account_id: ajehfe56h**********
x-yc-apigateway-websocket-message:
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95ic**********
tag: "$latest"
service_account_id: ajehfe56h**********
x-yc-apigateway-websocket-disconnect:
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95ic**********
tag: "$latest"
service_account_id: ajehfe56h**********