REST
An architectural style for APIs over HTTP using resources identified by URLs, verbs (GET/POST/PUT/PATCH/DELETE), and stateless interactions. It's cacheable, layered, and uses standard status codes. Most public web APIs are REST-ish.
- Public APIs, CRUD resources, anything benefiting from HTTP caching.
- When broad client interoperability matters.
- Complex graph queries (use GraphQL).
- Tight, schema-heavy internal RPC (use gRPC).
Definition
REST models an API as resources (/orders/42) manipulated via uniform HTTP methods with representations (JSON). Stateless requests, hypermedia links, and content negotiation are core; in practice most 'REST' APIs are HTTP/JSON CRUD over resources.
Why it exists
It uses the web's existing caching, routing, and semantics, giving interoperable, cacheable APIs without bespoke protocols. Resources map cleanly to domain objects.
How it works
Clients call URLs with verbs; servers return representations + status codes. Idempotent verbs (GET, PUT, DELETE) and non-idempotent POST. Caching via Cache-Control, ETag/If-None-Match. Pagination, filtering, and errors via conventions.
Scaling limits
N+1 problems: fetching a graph needs many round trips. Versioning is awkward (URL vs header). No built-in schema; clients guess shapes unless you add OpenAPI.
Cost shape
Cheap and universal (HTTP). The cost is over/under-fetching and the lack of a typed contract without OpenAPI tooling.
Alternatives
- GraphQL — Client-shaped queries, one endpoint, but harder caching and DoS surface.
- gRPC — Typed, efficient binary, but not browser-friendly without a gateway.
Failure modes
- Treating it as CRUD over tables with no domain modeling.
- Inconsistent error/status semantics across endpoints.