WebSocket Mastery: Implementation and Strategy

The O'Reilly ebook "Learning API-Styles" from 2025 focuses on the **WebSocket protocol and API style**, detailing its mechanics, implementation, security, and trade-offs. The content is structured as a technical chapter that guides the reader through building and securing WebSocket-based applications within a Weather Forecast Service (WFS) project.
The book defines WebSocket as a communication protocol designed for *simultaneous bidirectional (full-duplex) communication**. Unlike standard HTTP, which follows a **request-response model* where the server cannot initiate communication without a prior client request, WebSocket allows both parties to send messages independently over a single, long-lived TCP connection.
Establishing a connection involves a three-step *opening handshake* that begins with an HTTP request:
The client sends an HTTP `GET` request with specific headers: `Upgrade: websocket`, `Connection: Upgrade`, and a `Sec-WebSocket-Key`.
If the server supports the protocol, it returns an *HTTP 101 status code (Switching Protocols)* with a `Sec-WebSocket-Accept` header to validate the handshake.
Once the handshake is successful, the connection switches from HTTP to the custom TCP-based WebSocket protocol.
To secure WebSocket APIs, the book outlines several critical strategies:
Using middleware to check the `Origin` header to prevent unauthorized cross-origin access.
Limiting requests to those destined for specific, trusted hostnames to reduce HTTP host header attacks.
Since WebSocket doesn't support custom headers during the handshake, JSON Web Tokens (JWTs) are passed via *query parameters* and validated by the server before the connection is established.
Encrypting data in transit by using the *`wss://`* (WebSocket Secure) scheme instead of `ws://`.
The book introduces the *AsyncAPI Specification* as the standard for documenting asynchronous, event-driven APIs. It allows developers to define the operations (like receiving alerts), channels, and message schemas in a YAML or JSON format, similar to how OpenAPI is used for REST APIs.
The book concludes with a detailed analysis of the advantages and disadvantages of using WebSockets.
#websockets