REST principles

REST (Representational State Transfer) is an architectural style, not a protocol or a spec — Roy Fielding’s 2000 dissertation describing the constraints that made the web scale. An API is “RESTful” to the degree it honors those constraints; in practice most “REST APIs” are pragmatic HTTP+JSON APIs that satisfy the important ones.

The six constraints

Statelessness is covered in depth in Stateful vs Stateless (REST and beyond); caching in REST Error Handling and HTTP Caching.

The uniform interface — four sub-constraints

1. Identification of resources — every thing has a URI: /users/123, /orders/42/items.
2. Manipulation through representations — you never touch the resource itself, only representations of it (a JSON document you GET, modify, and PUT back).
3. Self-descriptive messages — each message carries enough to process it: method, Content-Type, cache headers (HTTP Semantics and Caching).
4. HATEOAS — responses link to available next actions. The most-cited, least-implemented constraint; see Richardson Maturity Model and HATEOAS for why level 2 is the industry plateau.

Resources and URI design

Resources are nouns; the methods are the verbs.

Conventions that hold up:

• Collections plural (/users), items by id (/users/123).
• Nest one level for ownership (/users/123/orders); deeper nesting (/users/123/orders/42/items/7) is brittle — items usually deserve a top-level URI once they have their own identity.
• Actions that don’t map to CRUD (cancel, approve, retry): model the action as a resource (POST /orders/42/cancellation) or accept a pragmatic verb sub-path (POST /orders/42/cancel). Both beat tunneling everything through PATCH with magic fields.

The action-as-resource move is worth seeing, because the cancellation then has its own identity — a timestamp, a reason, an author — which a magic field on the order cannot carry:

@router.post("/orders/{id}/cancellation", status_code=201)
async def cancel(id: str, body: CancellationIn) -> Cancellation:
    ...

# vs the alternative, which loses all of that:
# PATCH /orders/42  {"status": "cancelled"}

It also gives you somewhere to GET. “Why was this cancelled and by whom” is a question the PATCH version answers only from an audit log.

Methods and their contracts

The method grid — safety and idempotency are contracts you must uphold server-side, not descriptions that come true automatically:

Details and gotchas: PUT vs PATCH: Understanding the Difference, Idempotency (including idempotency keys for POST). Status-code discipline: Status codes.

Representations and content negotiation

A resource is not its JSON. The client asks for a representation via Accept, the server labels what it returns via Content-Type:

GET /users/123 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id": 123, "name": "Ada", "links": {"orders": "/users/123/orders"}}

REST does not mandate JSON — that’s convention. Versioning via media types (Accept: application/vnd.api.v2+json) vs URL is covered in REST Versioning and Pagination.

What “RESTful enough” means in practice

The pragmatic checklist most teams (and interviewers) actually mean:

1. Nouns for URIs, methods for verbs.
2. Correct status codes — not 200-with-{"error": ...}.
3. Stateless requests (auth via token per request).
4. GET is safe and cacheable; PUT/DELETE are idempotent.
5. Consistent error shape (RFC 7807 — REST Error Handling and HTTP Caching).
6. Pagination, filtering, versioning conventions (REST Versioning and Pagination).

HATEOAS is where most stop — that’s Richardson level 2, and it’s fine. Know why you’re not doing level 3, not just that you aren’t.

Common pitfalls

• Verbs in URLs (/api/getUsers) — RPC in REST clothing. If that’s what the domain wants, consider actual RPC (API Protocols Comparison — REST, GraphQL, gRPC, SOAP).
• 200 for everything, errors described only in the body — breaks caches, retries, monitoring, and every generic HTTP client.
• Chatty resources — forcing N+1 GETs for one screen. Compose (?include=), aggregate endpoints, or a BFF; don’t pretend the constraint doesn’t exist.
• PUT that partially updates — violates the replace contract; that’s PATCH’s job.
• Session state on the server (“the previous request selected the account”) — breaks statelessness and horizontal scaling.

Common interview confusions

• REST ≠ HTTP. REST is the style; HTTP is the protocol it’s usually expressed in. You can violate REST over HTTP (most RPC-ish APIs do) — and theoretically apply REST elsewhere.
• REST ≠ JSON. Representation format is negotiable.
• “RESTful” ≠ “has HATEOAS”. Fielding would say yes; industry means level 2. Know both readings.