Notesencoding🌱 seedling

REST

Also: RESTful API · Representational State Transfer · HTTP API · Safe Method · Idempotent Method

REST is an architectural style for networked APIs built on the web's own rules: resources named by URLs, a small uniform set of methods, stateless requests and cacheable responses. In practice it usually means JSON over HTTP with resource-shaped URLs.

Why it exists

The web scaled because any client could talk to any server through intermediaries that understood the protocol. REST names the constraints that made that work, so APIs can reuse the same machinery.

How it works

  • Constraints: client–server, stateless (each request carries everything needed), cacheable, layered (proxies and caches can sit between), uniform interface, and optional code-on-demand.
  • Uniform interface: resources identified by URLs, manipulated through representations, with self-descriptive messages (and, in the full style, hypermedia links).
  • Method semantics: GET, HEAD and OPTIONS are safe; PUT, DELETE and the safe methods are idempotent; POST is neither, so it needs idempotency keys to retry safely.
  • Tooling: OpenAPI documents describe endpoints and generate clients; HTTP caches, load balancers and curl all just work.

Trade-offs

Gains Costs
universal reach: browsers, proxies, caches verbose text encoding, no streaming in the basic model
easy to debug and explore interface contracts are by convention unless you adopt OpenAPI
caching and idempotency built into the method semantics resource modelling can be awkward for action-shaped operations

In practice

  • Public APIs (Stripe, GitHub) are JSON over HTTP, with API Versioning layered on top.
  • Internal high-volume calls often move to RPC frameworks like gRPC for compact encoding and streaming.

Pitfalls

  • Retrying POSTs without an idempotency key.
  • Clients that reject unknown response fields, turning additive server changes into breaking ones.

Recall

These cards are also in your review deck, scheduled with spaced repetition.