API design: contracts that survive retries

REST is an architectural style, not just JSON over HTTP. gRPC exposes typed procedures. GraphQL lets clients select graph fields; the server still owns authorization, query cost and data access.

A single GraphQL request can trigger many backend reads. Field selection can reduce overfetching, but query depth, resolver batching, authorization and cost limits remain server responsibilities.

WebSockets suit two-way interaction. SSE suits server-driven feeds; browser EventSource can reconnect and carry event IDs. Long polling holds an ordinary HTTP request until an event or timeout, then repeats. Every option needs reconnect and overload behavior.

Offset pagination names a position that can move. A cursor names a boundary in a stable total order, such as (created_at, id). Fetch after that boundary using the same filters and ordering. Cursors avoid this insertion shift, but do not create a snapshot.

Compatibility includes behavior, not just schemas. Additive fields are safe only when readers tolerate them. New enum values can break exhaustive clients. Use a migration window and explicit version boundary for incompatible changes; retire old versions only after client migration.

An idempotency key identifies one logical operation. Scope it to the caller and operation, bind it to the request payload, and retain its result. Concurrent requests require atomic deduplication with the effect. Reusing a key with a different payload must be rejected.

Deduplication is bounded by retention. After expiry, the same key may be treated as new. Persist a business identifier when duplicate effects must remain impossible beyond that window. A transport retry policy cannot supply permanent exactly-once business behavior.