Communicating with an API gateway using the WebSocket protocol
To connect to an API gateway via the WebSocket protocol:
If you no longer need the resources you created, delete them.
Getting started
Sign up for Yandex Cloud and create a billing account:
- Go to the management console and log in to Yandex Cloud or create an account if you do not have one yet.
- On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the
ACTIVEorTRIAL_ACTIVEstatus. If you do not have a billing account, create one.
If you have an active billing account, you can go to the cloud page to create or select a folder for your infrastructure to operate in.
Learn more about clouds and folders.
Required paid resources
The cost of the resources includes charges for the number of API gateway requests and outgoing traffic (see Yandex API Gateway pricing).
Create an API gateway
- In the management console, select the folder where you want to create an API gateway.
- In the list of services, select API Gateway.
- Click Create API gateway.
- In the Name field, enter
websocket. - (Optional) In the Description field, enter a description.
- In the Specification section, add a specification:
openapi: 3.0.0 info: title: Test API version: 1.0.0 paths: /connections: x-yc-apigateway-websocket-message: summary: Get connection identifier operationId: getConnectionID parameters: - name: X-Yc-Apigateway-Websocket-Connection-Id in: header description: Websocket connection identifier required: true schema: type: string responses: '200': description: Connection identifier content: text/plain: schema: type: string x-yc-apigateway-integration: type: dummy http_code: 200 http_headers: Content-Type: application/json content: text/plain: '{"connection_id":"{X-Yc-Apigateway-Websocket-Connection-Id}"}' - Click Create.
Establish a connection
- Open the terminal and install the wscat utility:
npm install -g wscat - Connect to the API gateway. Replace
<API_gateway_ID>with an API gateway ID.wscat -c wss://<API_gateway_ID>.apigw.yandexcloud.net/connections Connected (press CTRL+C to quit) - Type in any message and press
Enter.
The message will be sent to the API gateway via the existing connection. The API gateway will call integration and send a response that you will see on your screen. The response will contain the connection ID:
> Hello!
< {"connection_id":"<connection_ID>"}
Test the connection
Open a new terminal window and test the connection using the returned connection ID.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.
- Retrieve information on the existing connection:
yc serverless api-gateway websocket get <connection_ID> - Send a message to the client:
yc serverless api-gateway websocket send <connection_ID> --data Hello! - Close the connection:
yc serverless api-gateway websocket disconnect <connection_ID> - Go to the terminal window with the established connection. It should display the following information:
wscat -c wss://<API_gateway_ID>.apigw.yandexcloud.net/connections Connected (press CTRL+C to quit) > Hello! < {"connection_id":"<connection_ID>"} < Hello! Disconnected (code: 1000, reason: "")
How to delete the resources you created
To stop paying for the resources created, delete the API gateway.