Skip to content

API design & contracts

Designing HTTP APIs that hold up: method semantics, error contracts, versioning, pagination, idempotency, concurrency, rate limits, webhooks and uploads.

12 lessons

Resource semantics and the contract

  1. 1HTTP method semantics, safe, idempotent, PUT vs PATCH vs POSTA method is a promise about server state: safe changes nothing, and idempotent means once or five times ends the same.
  2. 2Status codes and the error contract (RFC 9457 Problem Details)The status line tells every tool what to do; the problem body tells your own client which error it was.
  3. 3Contract evolution: breaking changes, spec diffs, versioning and deprecationA request may accept more; a response may never send what an old client cannot read.

Collections

  1. 4Pagination, offset vs keyset/cursor, with filtering and sortingAn offset is a position in a list that keeps changing; a keyset cursor is the last row itself, found again by an index.

Reliability semantics

  1. 5Idempotency keys for unsafe operationsA key names one intended operation; a retained result lets repeats recover its outcome without repeating its effect.
  2. 6Optimistic concurrency over HTTP: ETag, If-Match, 412An ETag sent back in If-Match turns a silent overwrite into a 412 the client can merge from.
  3. 7Rate limitingChoose whose budget is counted, how it recovers, and which shared operation decides admission.
  4. 8Long-running operations: 202 Accepted plus a status resourceAccept, record, point: the reply says where to ask, and the record outlives every process that touched it.
  5. 9Webhooks: signing, replay protection, retries, idempotent receiversA webhook arrives at least once and from anyone: check its bytes, its time and its id, then answer fast.
  6. 10File uploads through presigned URLsA presigned URL is a short-lived bearer credential for one object: authorise and scope it before you sign, then believe storage, not the client.

API styles and topology

  1. 11Choosing an API style, REST vs GraphQL vs tRPC vs gRPCEach style moves a cost: REST pays in round trips, GraphQL in server work and caching, tRPC in coupling, gRPC in browser reach.
  2. 12Backend-for-Frontend vs API gatewayThe gateway does what every request needs; a BFF does what one user experience needs, and that experience's team runs it.