From 82d333ae8fd606457879e3f6d3cebfa4a1b51fdd Mon Sep 17 00:00:00 2001 From: Illia Malachyn Date: Tue, 7 Jan 2025 16:31:30 +0200 Subject: [PATCH] Add skeleton for new websockets stream api docs * Added a single page overiview docs * Added a multi-page detailed docs for each message type --- .../accessing-data/websockets-stream-api.md | 184 ++++++++++++++++++ .../list-subscriptions-message.md | 48 +++++ .../subscribe-message.md | 81 ++++++++ .../unsubscribe-message.md | 44 +++++ 4 files changed, 357 insertions(+) create mode 100644 docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/websockets-stream-api.md create mode 100644 docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/list-subscriptions-message.md create mode 100644 docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/subscribe-message.md create mode 100644 docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/unsubscribe-message.md diff --git a/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/websockets-stream-api.md b/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/websockets-stream-api.md new file mode 100644 index 0000000000..53ec078b78 --- /dev/null +++ b/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/websockets-stream-api.md @@ -0,0 +1,184 @@ +--- +title: Flow Websockets Stream API Specification +sidebar_label: Websockets Stream API +sidebar_position: 3 +--- + +# Flow Websockets Stream API Documentation + +## Overview + +The Stream API allows clients to receive real-time updates from the Flow blockchain via WebSocket connections. It +supports subscribing to various topics, such as blocks, events, and transactions, enabling low-latency access to live +data. + +### Important Information + +- **Endpoint**: The WebSocket server is available at: + ``` + wss://api.flow.com/ws + ``` +- **Limits**: + - Each connection supports up to 50 concurrent subscriptions. Exceeding this limit will result in an error. + - TODO: list all limits here +- **Supported Topics**: + - `blocks` + - `block_headers` + - `block_digests` + - `events` + - `transaction_statuses` + - `account_statuses` +- **Notes**: Always handle errors gracefully and close unused subscriptions to maintain efficient connections. + +--- + +## Setting Up a WebSocket Connection + +Use any WebSocket client library to connect to the endpoint. Below is an example using JavaScript: + +```javascript +const ws = new WebSocket('wss://api.flow.com/ws'); + +ws.onopen = () => { + console.log('Connected to WebSocket server'); +}; + +ws.onclose = () => { + console.log('Disconnected from WebSocket server'); +}; + +ws.onerror = (error) => { + console.error('WebSocket error:', error); +}; +``` + +--- + +## Subscribing to Topics + +To receive data from a specific topic, send a subscription request in JSON format over the WebSocket connection. + +### Request Format + +```json +{ + "subscription_id": "some-uuid-42", + "action": "subscribe", + "topic": "blocks", + "parameters": { + "start_block_height": "123456789" + } +} +``` + +- **`subscription_id`**: A unique identifier for the subscription (UUID string). If omitted, the server generates one. +- **`action`**: The action to perform. Supported actions include: `subscribe`, `unsubscribe`, `list_subscriptions`. +- **`topic`**: The topic to subscribe to. See the supported topics in the Overview. +- **`parameters`**: Additional parameters for subscriptions, such as `start_block_height`, `start_block_id`, and others. + +### Response Format + +```json +{ + "subscription_id": "some-uuid-42", + "error": null +} +``` + +--- + +## Unsubscribing from Topics + +To stop receiving data from a specific topic, send an unsubscribe request. + +### Request Format + +```json +{ + "subscription_id": "some-uuid-42", + "action": "unsubscribe" +} +``` + +### Response Format + +```json +{ + "subscription_id": "some-uuid-42", + "error": null +} +``` + +--- + +## Listing Active Subscriptions + +You can retrieve a list of all active subscriptions for the current WebSocket connection. + +### Request Format + +```json +{ + "action": "list_subscriptions" +} +``` + +### Response Format + +```json +{ + "subscriptions": [ + { + "subscription_id": "uuid-1", + "topic": "blocks", + "parameters": { + "start_block_height": "123456789" + } + }, + { + "subscription_id": "uuid-2", + "topic": "events", + "parameters": {} + } + ] +} +``` + +--- + +## Errors Example + +If a request is invalid or cannot be processed, the server responds with an error message. + +### OK Response + +```json +{ + "subscription_id": "some-uuid-42", + "payload": { + "id": "0x1234...", + "height:": "123456789", + "timestamp": "2025-01-02T10:00:00Z" + }, + "error": null +} +``` + +### Error Response + +```json +{ + "subscription_id": "some-uuid-42", + "payload": null, + "error": { + "code": 500, + "message": "Access Node failed" + } +} +``` + +### Common Error Codes + +- **400**: Invalid message format or parameters +- **404**: Subscription not found +- **500**: Internal server error diff --git a/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/list-subscriptions-message.md b/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/list-subscriptions-message.md new file mode 100644 index 0000000000..f6e74c5731 --- /dev/null +++ b/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/list-subscriptions-message.md @@ -0,0 +1,48 @@ +--- +title: List subscriptions request message format +sidebar_label: Listing subscriptions +sidebar_position: 3 +--- + +# List subscriptions message format + +List subscriptions requests must be sent as JSON in text frames, one request per frame. +This message is different from other as it doesn't require you to provide subscription ID. +Thus, the response for this message is different too. + +### Example of request + +```json +{ + "action": "list_subscriptions" +} +``` + +### Example of response + +```json +{ + "subscriptions": [ + { + "subscription_id": "uuid-1", + "topic": "blocks", + "parameters": { + "start_block_height": "123456789" + } + }, + { + "subscription_id": "uuid-2", + "topic": "events", + "parameters": {} + } + ] +} +``` + +If there are no active subscriptions, `subscriptions` array will be empty. + +### Request fields + +| Name | Type | Mandatory | Description | +|----------|--------|-----------|-----------------------------------------------------------------------------------------| +| `action` | STRING | YES | Action to perform. Must be `list_subscriptions` to initiate a list subscription request | diff --git a/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/subscribe-message.md b/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/subscribe-message.md new file mode 100644 index 0000000000..41e0bbc356 --- /dev/null +++ b/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/subscribe-message.md @@ -0,0 +1,81 @@ +--- +title: Subscribe request message format +sidebar_label: Subscribing to topic +sidebar_position: 1 +--- + +# Subscribe request format + +Subscribe requests must be sent as JSON in text frames, one request per frame. + +### Example of subscribe request + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786", + "action": "subscribe", + "topic": "block_digests", + "parameters": { + "start_block_height": "99,416,580" + } +} +``` + +### Example of successful response + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786" +} +``` + +### Example of failed response + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786", + "error": { + "code": 400, + "message": "invalid message" + } +} +``` + +### Example of messages provided by subscription (if successful) + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786", + "payload": { + "id": "0x1234...", + "height:": "123456789", + "timestamp": "2025-01-02T10:00:00Z" + } +} +``` + +### Example of messages provided by subscription (if error) + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786", + "error": { + "code": 500, + "message": "access node is not responsible" + } +} +``` + +### Request fields: + +| Name | Type | Mandatory | Description | +|-------------------|--------|-----------|--------------------------------------------------------------------------------------------| +| `subscription_id` | UUID | NO | Optional unique identifier for the subscription. Server will generate one if omitted | +| `action` | STRING | YES | Action to perform. Must be `subscribe` to initiate a subscription | +| `topic` | STRING | YES | The topic to subscribe to, such as `blocks`, `block_digests`, etc. | +| `parameters` | STRING | NO | Additional parameters for the subscription, such as `start_block_id`, `start_block_height` | + +You can use `subscription_id` as a client-generated identifier to track responses asynchronously. +If you don't provide `subscription_id`, the server will generate one and include it in the response. + +The order of params is not significant. diff --git a/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/unsubscribe-message.md b/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/unsubscribe-message.md new file mode 100644 index 0000000000..36e03151ce --- /dev/null +++ b/docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/unsubscribe-message.md @@ -0,0 +1,44 @@ +--- +title: Unsubscribe request message format +sidebar_label: Unsubscribing from topic +sidebar_position: 2 +--- + +# Unsubscribe message format + +Unsubscribe requests must be sent as JSON in text frames, one request per frame. + +### Example of unsubscribe request + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786", + "action": "unsubscribe" +} +``` + +### Example of successful response + +```json +{ + "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786" +} +``` + +### Example of error response + +```json +{ + "error": { + "code": 404, + "message": "subscription not found" + } +} +``` + +### Request fields + +| Name | Type | Mandatory | Description | +|-------------------|--------|-----------|-----------------------------------------------------------------------| +| `subscription_id` | UUID | YES | Unique identifier of the subscription | +| `action` | STRING | YES | Action to perform. Must be `unsubscribe` to initiate a unsubscription |