APIadvanced

WebSocket API Design

A bidirectional, full-duplex communication protocol over a persistent TCP connection for real-time data exchange between client and server.

Also known as: WebSocket Protocol, WS API, Real-Time Bidirectional API

Description

WebSocket APIs provide persistent, bidirectional communication between client and server, enabling real-time features like chat, collaborative editing, live trading, multiplayer games, and streaming telemetry. The connection starts as an HTTP upgrade request (101 Switching Protocols) and then operates as a raw TCP channel for sending frames in both directions with minimal overhead. Unlike SSE, WebSockets support binary data (ArrayBuffer, Blob) natively and allow both client-to-server and server-to-client messaging.

Designing a WebSocket API requires defining a message protocol since WebSockets only provide a raw frame transport. Common approaches include JSON messages with a type field ({ type: 'subscribe', channel: 'orders', filters: { userId: '...' } }), or binary protocols like Protocol Buffers for high-throughput scenarios. The API should define all supported message types, their schemas, and the expected responses or acknowledgments. Authentication typically happens during the HTTP upgrade handshake (via cookies or query-string tokens) since you can't set custom headers on the WebSocket constructor.

Operational concerns include connection management (heartbeat/pong frames to detect dead connections, reconnection with exponential backoff), horizontal scaling (WebSocket connections are stateful and sticky, requiring a pub/sub layer like Redis for broadcasting across server instances), and resource limits (maximum connections per server, message rate limiting per client). Libraries like Socket.IO add reliability features (auto-reconnection, room-based broadcasting, fallback to long-polling) but use a custom protocol that isn't compatible with raw WebSocket clients.

Prompt Snippet

Design the WebSocket message protocol with typed JSON frames: { type: 'subscribe' | 'unsubscribe' | 'rpc', id: string, payload: {} } with corresponding server frames: { type: 'event' | 'rpc_response' | 'error', id?: string, payload: {} }. Authenticate during the HTTP upgrade handshake by validating the Bearer token in the Sec-WebSocket-Protocol header or via a short-lived ticket parameter (?ticket=xyz). Implement ping/pong frames every 30 seconds to detect stale connections. Use Redis Pub/Sub to broadcast events across horizontally scaled WebSocket server instances. Enforce per-connection message rate limits of 100 msg/sec.

Related Terms

API

intermediate

Server-Sent Events (SSE)

A unidirectional HTTP streaming protocol where the server pushes real-time text-based events to the client over a persistent connection.

API

advanced

gRPC

A high-performance RPC framework using Protocol Buffers for schema definition and HTTP/2 for transport, optimized for service-to-service communication.

API