What REST Is (and Isn't) — REST APIs in Depth

REST (Representational State Transfer) is an architectural style defined by constraints: client–server, stateless requests, cacheable responses, a uniform interface (resources identified by URIs, manipulated through representations, self-descriptive messages, hypermedia), a layered system, and optional code-on-demand. In industry, "REST API" usually means a resource-oriented JSON-over-HTTP API that uses HTTP methods and status codes correctly — Richardson maturity level 2. Full hypermedia (level 3) is rare outside a few domains.

What matters in practice: predictable resource URLs, correct HTTP semantics (safe/idempotent methods, status codes, caching), statelessness so any server can handle any request, and consistency across every endpoint.

Richardson maturity model

Level	What it looks like	Example
0 — RPC over HTTP	One endpoint, action in the body	POST /api {"action":"getOrder","id":7}
1 — Resources	Separate URLs per resource, but one method	POST /orders/7/get
2 — HTTP verbs	Resources + correct methods and status codes	GET /orders/7 → 200 / 404
3 — Hypermedia	Responses include links to next actions	{"_links": {"cancel": {"href": "/orders/7/cancel"}}}

Common pitfalls

Calling any JSON endpoint 'REST' while tunnelling everything through POST.
Server-side session state that pins clients to one instance.
Debating purity instead of agreeing on a style guide and applying it consistently.

Key points

REST = constraints, not 'JSON over HTTP'
Level 2 is the industry norm
Statelessness and correct HTTP semantics matter most

Further reading: Fielding: REST dissertation, chapter 5

Practice questions

What does 'stateless' mean in REST, and why does it matter?

Answer

Each request contains everything the server needs (auth, parameters); the server keeps no client session between requests. Any instance can serve any request, which enables horizontal scaling, simple load balancing and caching.

Why is Richardson level 3 (HATEOAS) rare in practice?

Answer

Most clients are hand-written against documented URLs and don't navigate by links; hypermedia adds payload and design effort for limited benefit. It's valuable for workflow-heavy APIs and long-lived evolvable integrations.