Add websockets stream api docs

docs/networks/access-onchain-data/websockets-stream-api/_category_.yml

@@ -0,0 +1,2 @@
+label: "WebSockets Stream API"
+position: 3

docs/networks/access-onchain-data/websockets-stream-api/common-errors.md

@@ -0,0 +1,85 @@
+---
+title: Common errors
+sidebar_label: Common errors
+sidebar_position: 7
+---
+
+This document outlines the possible errors returned from the WebSocket API. Understanding these errors will help properly handle error cases in client implementation.
+
+## Error Structure
+
+All errors returned by the WebSocket API follow this structure:
+
+```json
+{
+  "subscriptionID": "string",
+  "error": {
+    "code": number,
+    "message": "string"
+  },
+  "action": "string"
+}
+```
+
+Where:
+- `subscriptionID`: The ID of the subscription related to the error (if applicable)
+- `error.code`: HTTP status code indicating the error type
+- `error.message`: Human-readable description of the error
+- `action`: The action that was being performed when the error occurred (`subscribe`, `unsubscribe`, or `list_subscription`)
+
+
+### Message Format Errors
+
+**Status Code:** 400 Bad Request
+
+These errors occur when the server cannot parse or validate your incoming message.
+
+| Error Message | Description | When to Expect |
+|---------------|-------------|---------------|
+| *"error reading message: ..."* | The raw message could not be read from the WebSocket connection | When sending malformed JSON or when the connection is disrupted |
+| *"error parsing message: ..."* | The message was read but could not be processed | When the message structure doesn't match the expected format |
+| *"error unmarshalling base message: ..."* | The message JSON could not be processed into the expected format | When required fields are missing or of incorrect type |
+| *"error unmarshalling subscribe message: ..."* | The message JSON could not be processed into a subscribe request | When sending a malformed subscribe request |
+| *"error unmarshalling unsubscribe message: ..."* | The message JSON could not be processed into an unsubscribe request | When sending a malformed unsubscribe request |
+| *"error unmarshalling list subscriptions message: ..."* | The message JSON could not be processed into a list subscriptions request | When sending a malformed list subscriptions request |
+| *"unknown action type: ..."* | The action specified in the message is not recognized | When specifying an action other than `subscribe`, `unsubscribe`, or `list_subscription` |
+
+## Subscription-Related Errors
+
+### Subscribe Action Errors
+
+**Action:** `subscribe`
+
+| Error Message | Status Code | Description | When to Expect |
+|---------------|-------------|-------------|---------------|
+| *"error creating new subscription: maximum number of subscriptions reached"* | 429 Too Many Requests | The maximum number of active subscriptions per connection has been reached | When trying to create more subscriptions than allowed by the server |
+| *"error parsing subscription id: ..."* | 400 Bad Request | The provided subscription ID is invalid | When providing a malformed subscription ID |
+| *"subscription ID is already in use: ..."* | 400 Bad Request | The provided subscription ID is already being used | When trying to reuse an existing subscription ID |
+| *"error creating data provider: ..."* | 400 Bad Request | The subscription could not be created | When providing an invalid topic or arguments for your subscription |
+
+### Unsubscribe Action Errors
+
+**Action:** "unsubscribe"
+
+| Error Message | Status Code | Description | When to Expect |
+|---------------|-------------|-------------|---------------|
+| *"error parsing subscription id: ..."* | 400 Bad Request | The provided subscription ID is invalid | When providing a malformed subscription ID |
+| *"subscription not found"* | 404 Not Found | The specified subscription does not exist | When trying to unsubscribe from a non-existent subscription |
+
+### Subscription Runtime Errors
+
+**Action:** "subscribe"
+
+| Error Message | Status Code | Description | When to Expect |
+|---------------|-------------|-------------|---------------|
+| *"internal error: ..."* | 500 Internal Server Error | An error occurred while processing your subscription | When there's an issue with the subscription after it was successfully created |
+
+## Error Handling Best Practices
+
+1. **Always check for errors in responses**: Every response from the WebSocket API should be checked for the presence of an error object.
+
+2. **Handle subscription limits**: Be prepared to handle the case where the maximum number of subscriptions has been reached.
+
+3. **Log detailed error information**: Log the complete error object for debugging purposes.
+
+4. **Validate messages before sending**: Ensure your messages conform to the expected format to avoid parsing errors.

docs/networks/access-onchain-data/websockets-stream-api/index.md

@@ -0,0 +1,196 @@
+---
+title: Overview
+sidebar_label: Overview
+sidebar_position: 1
+---
+
+# Websockets Stream API
+
+## 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:
+    - Mainnet: `wss://rest-mainnet.onflow.org/v1/ws`
+    - Testnet: `wss://rest-testnet.onflow.org/v1/ws`
+- **Limits**:
+    - Each connection supports up to 20 concurrent subscriptions. Exceeding this limit will result in an error.
+    - Each subscription may provide up to 20 responses per second. 
+    - After 1 minute of inactivity (no data sent or received) the connection is closed. 
+
+- **Supported Topics**: See more details on [Supported Topics](supported-topics/index.md) page.
+    - [`block_digests`](supported-topics/block_digests_topic.md)
+    - [`block_headers`](supported-topics/block_headers_topic.md)
+    - [`blocks`](supported-topics/blocks_topic.md)
+    - [`events`](supported-topics/events_topic.md)
+    - [`account_statuses`](supported-topics/account_statuses_topic.md)
+    - [`transaction_statuses`](supported-topics/transaction_statuses_topic.md)
+    - [`send_and_get_transaction_statuses`](supported-topics/send_and_get_transaction_statuses_topic.md)
+
+- **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://rest-mainnet.onflow.org/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-id-42",
+  "action": "subscribe",
+  "topic": "blocks",
+  "arguments": {
+    "block_status": "sealed",
+    "start_block_height": "123456789"
+  }
+}
+```
+
+- **`subscription_id`**(optional): A unique identifier for the subscription (a string with maximum length constraint of 20 characters). 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.
+- **`arguments`**: Additional topic specific arguments for subscriptions, such as `start_block_height`, `start_block_id`, and others. See more details about arguments for each topic on [Supported Topics](supported-topics/index.md) page.
+
+### Successful Response Format
+
+```json
+{
+  "subscription_id": "some-id-42",
+  "action": "subscribe"
+}
+```
+
+---
+
+## Unsubscribing from Topics
+
+To stop receiving data from a specific topic, send an unsubscribe request.
+
+### Request Format
+
+```json
+{
+  "subscription_id": "some-id-42",
+  "action": "unsubscribe"
+}
+```
+
+### Successful Response Format
+
+```json
+{
+  "subscription_id": "some-id-42",
+  "action": "unsubscribe"
+}
+```
+
+---
+
+## Listing Active Subscriptions
+
+You can retrieve a list of all active subscriptions for the current WebSocket connection.
+
+### Request Format
+
+```json
+{
+  "action": "list_subscriptions"
+}
+```
+
+### Successful Response Format
+
+```json
+{
+  "subscriptions": [
+    {
+      "subscription_id": "some-id-1",
+      "topic": "blocks",
+      "arguments": {
+        "block_status": "sealed",
+        "start_block_height": "123456789"
+      }
+    },
+    {
+      "subscription_id": "some-id-2",
+      "topic": "events",
+      "arguments": {}
+    }
+  ]
+}
+```
+
+---
+
+## Errors Example
+
+If a request is invalid or cannot be processed, the server responds with an error message.
+
+### OK Response
+
+```json
+{
+  "subscription_id": "some-id-42",
+  "topic": "block_digests",
+  "payload": {
+    "id": "0x1234...",
+    "height:": "123456789",
+    "timestamp": "2025-01-02T10:00:00Z"
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "subscription_id": "some-id-42",
+  "error": {
+    "code": 500,
+    "message": "Access Node failed"
+  }
+}
+```
+
+### Common Error Codes
+
+- **400**: Invalid message format or arguments
+- **404**: Subscription not found
+- **500**: Internal server error
+
+### Asynchronous environments
+
+If you're working in an asynchronous environment, the Streaming API ensures **first-in first-out** message processing, 
+so responses will be returned in the same order the requests were received over the connection.
+You can leverage this feature to simplify your code and maintain consistency.
+
+Additionally, you can specify a custom `subscription_id` in the subscribe request to easily identify the correct response. It must not be an empty string and must follow a maximum length constraint of 20 characters.

docs/networks/access-onchain-data/websockets-stream-api/list-subscriptions-message.md

@@ -0,0 +1,49 @@
+---
+title: List subscriptions request message format
+sidebar_label: Listing subscriptions
+sidebar_position: 5
+---
+
+# List subscriptions message format
+
+List subscriptions requests must be sent as JSON in text frames, one request per frame.
+This message is different from others 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": "some-id-1",
+      "topic": "blocks",
+      "arguments": {
+        "block_status": "finalized",
+        "start_block_height": "123456789"
+      }
+    },
+    {
+      "subscription_id": "some-id-2",
+      "topic": "events",
+      "arguments": {}
+    }
+  ]
+}
+```
+
+If there are no active subscriptions, `subscriptions` array will be empty.
+
+### Request fields
+
+| Name     | Type   | Required | Description                                                                             |
+|----------|--------|----------|-----------------------------------------------------------------------------------------|
+| `action` | STRING | YES      | Action to perform. Must be `list_subscriptions` to initiate a list subscription request |

docs/networks/access-onchain-data/websockets-stream-api/postman-example.md

@@ -0,0 +1,51 @@
+---
+title: Connecting to WebSockets via Postman UI
+sidebar_label: Connecting to WebSockets via Postman UI
+sidebar_position: 6
+---
+
+This tutorial will guide you through connecting to a WebSocket using Postman and sending a subscription message.
+
+## Step 1: Open Postman
+
+Ensure you have Postman installed and opened on your system. If you don’t have it yet, download it from [Postman’s official website](https://www.postman.com/downloads/).
+
+## Step 2: Create a New WebSocket Request
+
+1. In Postman, click on **File** > **New...** > **WebSocket**.
+![pe_1](<assets/pe_1.png>)
+2. Enter the WebSocket URL in **Enter URL** field : `wss://rest-mainnet.onflow.org/v1/ws` or `wss://rest-testnet.onflow.org/v1/ws`
+3. Click **Connect** button to establish the WebSocket connection.
+![pe_2](<assets/pe_2.png>)
+
+## Step 3: Send a Subscription Message
+
+1. Once connected, go to the **Messages** tab.
+2. Enter the JSON message into the text box. In this example the [digests block subscription](./supported-topics/block_digests_topic.md) will be established. For other available topics check [Supported topics page](./supported-topics/index.md).
+3. Click **Send** to subscribe to the WebSocket topic.
+![pe_3](<assets/pe_3.png>)
+
+## Step 4: View Responses
+
+- After sending the message, you should start receiving responses in the **Response** bottom tab.
+- Each message received from the server will be displayed in real-time.
+
+![pe_4](<assets/pe_4.png>)
+
+## Step 5: Disconnect
+
+- When you are done, click **Disconnect** to close the WebSocket connection.
+
+## Troubleshooting
+
+- Ensure WebSocket URL is correct and active.
+- In case of an error validate your JSON message for any syntax errors before sending and check correctness of all arguments on [Supported topics page](./supported-topics/index.md). 
+
+Congratulations! You have successfully connected to a WebSocket server using Postman and sent a subscription message.
+
+
+
+
+
+
+