API Protocols — defaults¶
Loaded by Config Resolution when a project has no override, or as the base layer under an overlay.
1. Choosing¶
Choose from the interaction shape, then check it against the estate's existing choice.
| The interaction | Protocol | Why |
|---|---|---|
| Client asks, server answers; resources with lifecycles | REST | Universal tooling, HTTP caching, every proxy understands it |
| Many varied clients needing different subsets, one round trip | GraphQL | Client-specified shape; removes over-fetching and chatty screens |
| High-volume internal calls, strict contracts, streaming | gRPC | Schema-first, efficient binary framing, first-class deadlines and streams |
| Server pushes to the client, one direction | SSE | Plain HTTP, auto-reconnect built in, trivial to operate |
| Both directions, frequently, low latency | WebSocket | Full duplex — accept the operational cost deliberately |
| Producer and consumer must be decoupled in time | Messaging | Not a protocol choice — a design choice (see api-contracts) |
| Batch or bulk transfer | File or object storage | An API is the wrong shape for a million rows |
Two rules that override the table:
- Estate consistency usually wins. A second protocol doubles the client libraries, the auth integration, the observability setup, the gateway configuration, and the on-call knowledge. Introduce one only for a force the existing protocol genuinely cannot meet.
- Check reachability first. A browser cannot speak gRPC without a gateway or grpc-web. A partner's firewall may not pass WebSockets. Solve that before designing.
2. REST¶
- Resources are nouns; the method is the verb.
POST /orders/{id}/cancellation, notPOST /orders/cancel. Operations with business meaning get their own sub-resource (seeapi-contracts). - Honour the method semantics.
GETandHEADare safe and cacheable and must never mutate — they will be prefetched, retried, and cached whether you intended it or not.PUTandDELETEare idempotent.POSTis neither, which is why it needs an idempotency key. - Use status codes properly.
200with{"success": false}throws away the one signal every proxy, client, and dashboard already understands. - Caching is a feature, not a default. Set
Cache-Controldeliberately on every response, includingno-storewhere that is right. UseETagwith conditional requests for large or frequently re-fetched resources. - Conditional writes with
If-Matchgive you optimistic concurrency over HTTP for free (seedata-access). - Content negotiation stays simple. One representation per resource unless there is a real need.
- HTTP/2 changes the cost model. Multiple small requests are far cheaper than they were, which weakens the usual argument for a bespoke aggregated endpoint.
3. GraphQL¶
GraphQL moves query planning from the server to the client. That is its value and its entire risk profile: the client can now write a query that nobody load-tested.
Schema design
- Design the graph around domain relationships, not around the current screens. Screens change.
- Nullability is a contract: non-null means you can always produce a value, including when a downstream call fails. Over-using non-null makes one failing field null out its entire parent.
- Enums and unions over stringly-typed fields. Interfaces for genuine polymorphism.
- Mutations return the modified object plus a typed result, so the client needs no re-fetch —
this is also the cleanest answer to read-your-writes (see
cqrs-and-consistency). - Errors: transport and validation failures use the
errorsarray; expected business failures belong in the result type as a union, so clients handle them with the type system rather than by matching strings. - Deprecate rather than remove.
@deprecatedplus field-level usage metrics tells you when it is safe to delete (seeapi-contracts).
The two failure modes
- N+1 resolvers. A list of 100 orders whose
customerresolver fetches per order issues 101 queries. Every per-parent resolver must batch — collect the keys for one tick, fetch them in one call, distribute the results. This is not an optimisation; it is the baseline. - Unbounded queries. Without limits, a nested query is a denial of service that requires no special access. Enforce: maximum depth, complexity/cost budget with per-field costs, maximum result size, and timeouts. For a first-party client, persisted queries are the strongest answer — the server accepts only a known allowlist of query documents, which caps the cost and enables caching.
Security. Authorise at the field and object level, not at the entry point — the graph makes
every edge an access path (see secure-service). Disable introspection for unauthenticated callers
in production. Watch for object-level authorisation gaps reached through nested relationships,
which is the graph version of the most common API vulnerability.
Observability. One /graphql endpoint makes every dashboard useless by default. Instrument by
operation name and resolver, and require clients to name their operations.
4. gRPC¶
Service and message design
- One service per bounded capability; methods named as operations.
- Never reuse a field number, and always
reserveda removed field's number and name. Reusing one silently corrupts data for clients built against the old schema. - Everything is optional in proto3 semantics — design for absent fields rather than assuming
presence. Avoid
requiredwhere the syntax still offers it. - Wrap request and response in their own message types, even for a single field, so fields can be added later without a signature change.
- Enums start at zero with an
UNSPECIFIEDvalue, so an unset field is distinguishable from the first real value. - Run
buf breaking(or the equivalent) in CI. Protobuf's compatibility rules are precise and easy to violate by accident.
Runtime
- Deadlines on every call, propagated downstream. gRPC makes this first-class; use it
(see
resilience-patterns). - Status codes carry meaning —
NOT_FOUND,ALREADY_EXISTS,FAILED_PRECONDITION,RESOURCE_EXHAUSTED. Map them properly instead of returningINTERNALfor everything, and use the details mechanism for structured error information. - Streaming needs flow control and cancellation. A server stream with no backpressure and no cancellation is an unbounded buffer. Always bound the stream and honour client cancellation.
- Load balancing is per connection, not per request, so a long-lived channel pins to one backend. Use a load-balancing policy or a proxy that understands HTTP/2 — otherwise traffic concentrates after any restart.
- Browsers need grpc-web or a gateway. Decide which before designing the API.
5. WebSockets and SSE¶
Long-lived connections make a stateless service stateful. Everything below follows from that.
Prefer SSE when the flow is server-to-client only. It is plain HTTP, works through ordinary
proxies, reconnects automatically, and supports resumption via Last-Event-ID with no protocol of
your own. Most "we need WebSockets" requirements are satisfied by SSE plus ordinary POSTs.
Design these explicitly, in this order:
- Authentication at handshake, and a decision about token expiry mid-connection — a connection opened an hour ago should not still be authorised on an expired token. Re-authenticate or close.
- Authorisation per subscription, not just per connection.
- Heartbeat in both directions, so half-open connections — the kind a network partition leaves behind — are detected rather than lingering.
- Idle timeout so abandoned connections are reclaimed.
- Reconnection with exponential backoff and full jitter. Without jitter, a server restart
brings every client back simultaneously and the service falls over again
(see
resilience-patterns). - Resume semantics. A sequence number or cursor the client sends on reconnect, and a bounded server-side buffer to replay from. Without this, every reconnect is a silent gap.
- Backpressure. Bound the per-connection outbound queue. When a slow client fills it, drop with a defined policy (oldest, or coalesce) and tell the client — never buffer without limit.
- Connection limits per user and per instance, and a plan for what happens at the cap.
Operationally: connections pin clients to instances, so a deploy disconnects everyone at once — stagger it. Per-connection state in memory is lost on restart; keep it in a shared store or make it reconstructible. Load balancers need idle timeouts longer than your heartbeat interval, or they will close healthy connections. And a fan-out to many connections needs a broker behind it, because one instance holds only its own share.
Message framing: version the message envelope from day one; include a type field and a sequence number. A socket protocol with no version field is impossible to evolve.