Communication Patterns
HTTP and its evolution, RPCs, WebSockets, and the textual + binary data formats every API designer must read fluently.
Once you've chosen to design an API, the next decision is how to move the bytes. HTTP is the default — but HTTP 1.1, HTTP/2, and HTTP/3 differ in ways that affect API design (multiplexing, head-of-line blocking, the QUIC handshake). Below HTTP sits RPC (function-call-shaped) and above it sit WebSockets (long-lived bidirectional). The choice shapes the contract.
And then there's the payload. JSON won, but XML still ships in enterprise APIs and YAML still configures everything. Protobuf, MessagePack, and Avro buy you wire efficiency at the cost of debuggability. Picking the format for an API is as load-bearing as picking the verb.
Key concepts
- HTTP is the default, but HTTP/2 and HTTP/3 change the multiplexing story significantly
- RPC is request/response framed as a function call — its leaks are well-documented
- WebSockets is the long-lived bidirectional escape from HTTP's request/response shape
- JSON is the lingua franca; XML still lives in older enterprise APIs
- Binary formats (Protobuf, Avro, MessagePack) trade debuggability for wire size and parsing speed
Reference template
// Picking a communication pattern
1. Is the interaction request/response or push? (HTTP vs WebSockets vs SSE)
2. Is the client polyglot? (REST/HTTP wins; gRPC requires codegen)
3. Is payload size dominant? (binary formats; otherwise JSON)
4. Is schema evolution central? (Protobuf/Avro give you that for free)
5. Is the call truly function-call-shaped? (then RPC); else RESTAdapt to your problem; the structure is the load-bearing part.
Common pitfalls
- Choosing HTTP/2 in production then hitting a load balancer that downgrades to 1.1
- Using WebSockets where SSE or long-polling would have been simpler
- Picking Protobuf when nobody on the team can debug binary payloads at 3am
- Letting YAML's whitespace bite a deploy because someone copy-pasted from a doc
Related topics
Items (7)
- Data Representation and Efficient Communication
On the wire, every API is bytes. The trade-off between human-readable and compact, and why both have their place.
Concept Foundational - HTTP — The Foundational Protocol for APIs
Methods, status codes, headers, persistent connections — the parts of HTTP every API designer must own.
Building Block Foundational - The Evolution of HTTP — 1.1, 2, 3
Pipelining → multiplexing → QUIC. How each version solved the previous one's head-of-line problem and what that buys API designers.
Building Block Intermediate - Remote Procedure Calls (RPCs)
Calling a remote function as if it were local. The 'function-call' abstraction, its leaks, and where it's still the right call.
Building Block Intermediate - WebSockets — Bidirectional Streaming
Upgrade-handshake, full-duplex frames, the long-lived connection model. When push beats poll.
Building Block Intermediate - Textual Data Formats — JSON, XML, YAML
The trio every API designer must read fluently. Why JSON won, where XML still lives, what YAML costs in subtle bugs.
Building Block Foundational - Binary Data Formats — Protobuf, MessagePack, Avro
When the wire matters more than the diff. Schema-first vs schema-less, evolution semantics, the size-vs-debuggability trade-off.
Building Block Intermediate