jdfive

REST Constraints

REST is a style, not a format

REST stands for Representational State Transfer. Roy Fielding described it in his PhD dissertation as an architectural style: a set of constraints that, when applied together, yield desirable properties — independent evolution of client and server, horizontal scaling, cacheability, and visibility of interactions through a uniform interface.

REST is not the same thing as “any JSON API over HTTP.” Teams say “REST” when they mean “we expose HTTP endpoints with JSON bodies.” That is REST-ish at best. Interviewers care that you know the difference: JSON is a representation format; REST is a constraint set you can apply more or less strictly.

The core constraints

Client–server

Separate UI concerns from data storage. The client does not need to know whether data lives in PostgreSQL or a document store; the server does not need to know whether the client is a mobile app or a CLI. Each side can evolve independently as long as the interface (resources, representations, methods) stays stable or versioned.

Stateless

The server must not depend on server-side session memory to interpret a request. Each request carries whatever the server needs: credentials, resource identifiers, conditional headers. The next chapter on Statelessness unpacks what still counts as REST-ish (Authorization headers, opaque cookies) vs what breaks the constraint (sticky session RAM required for correctness).

Cacheable

Responses can be labeled cacheable or not. Intermediaries (CDNs, reverse proxies, corporate gateways) and clients can reuse cacheable GET responses when validators (ETag, Last-Modified) say it is safe. This constraint is why GET semantics and URL design matter for read-heavy public APIs.

Uniform interface

Four sub-constraints work together:

  1. Identification of resources — every resource has a URI.
  2. Manipulation through representations — clients send and receive representations (JSON, XML, HTML), not “the resource itself.”
  3. Self-descriptive messages — requests and responses carry enough metadata (Content-Type, method, status) to be understood without out-of-band knowledge.
  4. Hypermedia as the engine of application state (HATEOAS) — ideally, responses include links (rel, href) so clients discover actions dynamically. Most JSON APIs skip full HATEOAS; knowing it exists shows you read the original style.

Layered system

Clients cannot tell whether they talk to the origin server or an intermediary (load balancer, API gateway, CDN). Layers can enforce security, caching, or rate limits without changing client code — as long as the uniform interface is preserved.

Code on demand (optional)

Servers may extend client behavior by sending executable code (historically JavaScript). Fielding lists this as optional; most public APIs omit it.

What “RESTful” buys you

When teams apply these constraints seriously:

  • Scaling — stateless app tiers add instances without session affinity.
  • Caching — GET + cache headers offload read traffic to CDNs.
  • Intermediaries — proxies can log, authenticate, or transform without bespoke client plugins.
  • Evolution — clients and servers version representations independently.

When teams skip constraints, they still ship working products. The interview skill is naming what you gave up: no cache-friendly reads, hidden coupling to session state, RPC-shaped URLs that gateways cannot reason about generically.

REST-ish in practice

Production JSON APIs commonly:

  • Use nouns in paths and verbs in HTTP methods (see Resources & URIs).
  • Return 201 + Location on create, 204 on delete, structured 4xx/5xx (see Status Codes & Errors).
  • Stay stateless at the application tier (tokens in headers, not server session maps).
  • Omit HATEOAS but keep paths predictable enough for OpenAPI docs and client codegen.

That is a pragmatic subset. Calling it “REST” in a standup is fine; in an interview, say REST-ish or resource-oriented HTTP when you mean JSON CRUD without hypermedia.

Interview framing

“What is REST?” — An architectural style: clients manipulate representations of resources through a uniform interface, with stateless servers and cacheable responses where appropriate. HTTP is the common carrier; JSON is one representation format.

“Is every HTTP API RESTful?” — No. RPC-shaped POST /doThing, session state required on the server, or using GET for mutations all violate constraints. Many APIs are intentionally pragmatic.

“Do I need HATEOAS?” — Rarely in mobile/SPA clients that ship with generated SDKs. Mention it as the ideal uniform interface; describe links in responses if the interviewer pushes on discoverability.

Next: Resources & URIs — how to name what you expose.