Scott.Idem/OSIT-AE-API-FastAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: fix WS guide - client_id/group_id are opaque strings, not required Vision IDs

Browse Source
This commit is contained in:
Scott Idem
2026-03-11 19:02:06 -04:00
parent c30631cb7d
commit c7c14e8047
1 changed files with 11 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
View File

@@ -19,12 +19,19 @@ This guide explains how to implement real-time communication using the **Aether
## 2. Connection Strategy ## 2. Connection Strategy
### A. Endpoint URL ### A. Endpoint URL
The V3 WebSocket path requires both a `group_id` and a `client_id` (using **Vision ID** random strings). The V3 WebSocket path requires both a `group_id` and a `client_id`. Both are treated as **opaque unique strings** by the backend — no specific format is enforced.
```text ```text
wss://[api_domain]/v3/ws/group/{group_id}/client/{client_id} wss://[api_domain]/v3/ws/group/{group_id}/client/{client_id}
``` ```
**`group_id`** — identifies the shared channel (e.g., an event ID, a room name, or a Vision ID random string). All clients using the same `group_id` receive group-targeted messages together.
**`client_id`** — uniquely identifies this specific connection. Common choices:
- `Date.now()` timestamp (e.g. `1773266158823`) — simple and collision-resistant for short-lived sessions
- A UUID (`crypto.randomUUID()`)
- A Vision ID random string if you need the client to be addressable by a known database identity
> Use `ws://` for local development and `wss://` in production (any HTTPS site). The Nginx config must include the Upgrade block — see Section 6. > Use `ws://` for local development and `wss://` in production (any HTTPS site). The Nginx config must include the Upgrade block — see Section 6.
### B. Authentication ### B. Authentication
@@ -43,8 +50,8 @@ wss://dev-api.oneskyit.com/v3/ws/group/{group_id}/client/{client_id}?api_key=<ke
### C. Connection Example (TypeScript) ### C. Connection Example (TypeScript)
```ts ```ts
const group_id = "group_abc123"; // Random Vision ID const group_id = "event_abc123"; // Any unique string identifying the shared channel
const client_id = "device_xyz789"; // Random Vision ID const client_id = String(Date.now()); // Any unique string identifying this client connection
const api_key = import.meta.env.VITE_API_KEY; const api_key = import.meta.env.VITE_API_KEY;
const jwt = getSessionToken(); // your JWT helper const jwt = getSessionToken(); // your JWT helper
@@ -188,5 +195,5 @@ If you are upgrading from the legacy V2 WebSocket (`/ws/group/...`):
1. **Change the URL**: Prepend `/v3/` to your WebSocket path. 1. **Change the URL**: Prepend `/v3/` to your WebSocket path.
2. **Wrap your JSON**: In V2, you might have sent `{"msg": "hi"}`. In V3, this must be `{"msg_type": "msg", "target": "group", "msg": "hi"}`. 2. **Wrap your JSON**: In V2, you might have sent `{"msg": "hi"}`. In V3, this must be `{"msg_type": "msg", "target": "group", "msg": "hi"}`.
3. **Use Vision IDs**: Ensure all IDs passed in the path and `to_id` fields are the random string IDs (`id_random`), not database integers. 3. **Use unique string IDs**: Both `group_id` and `client_id` in the path are opaque strings — any unique value works (timestamp, UUID, Vision ID random string). Just don't use raw database integer IDs. For `to_id` in direct messages, use whatever `client_id` that target client registered with.
4. **Listen for `msg_type`**: Update your frontend handlers to switch logic based on the `msg_type` field instead of proprietary keys. 4. **Listen for `msg_type`**: Update your frontend handlers to switch logic based on the `msg_type` field instead of proprietary keys.