REST architecture.

Where REST came from

In 2000, a researcher named Roy Fielding wrote a doctoral dissertation that retroactively described the architecture of the web — why HTTP scaled when other protocols didn't. He gave it a name: REST (Representational State Transfer).

So REST is not a protocol. It's not a format. It's a set of architectural constraints. If your API satisfies them, it's RESTful. If not, it's just an API. (Both are fine — but pretending matters.)

The six constraints

The first five matter. The sixth is a footnote — Fielding even marked it optional.

The mental model · resources

The single most useful insight from REST: your API is a collection of resources, not a collection of actions.

Nesting resources

Sub-resources express ownership:

GET    /users/42/orders          # orders for user 42
POST   /users/42/orders          # create an order for user 42
GET    /users/42/orders/9        # specific order
DELETE /users/42/orders/9        # remove it

Two informal rules in practice:

• Don't nest more than 2 levels. /users/42/orders/9/items/3 is too deep — make /items/3 a top-level resource.
• Filter via query params, not paths. GET /orders?userId=42&status=paid&sort=createdAt over deep paths.

Statelessness — the constraint that scales

"Each request contains everything to process it" sounds abstract. Concretely:

POST /login
→ server stores session
→ returns session-id

GET /me
→ server looks up session
→ from in-memory map

POST /login
→ returns signed JWT

GET /me
Authorization: Bearer eyJ...
→ verify token signature
→ all info in the token

Cacheable — leverage the network

HTTP caching is built into the protocol. Use it:

GET /products/42 HTTP/1.1\n\nHTTP/1.1 200 OK\nCache-Control: public, max-age=3600\nETag: "abc123"

The Cache-Control: max-age=3600 tells browsers, CDNs, proxies — "you can cache this for an hour." A subsequent request can be answered from cache without ever hitting your server.

ETag + If-None-Match lets clients ask "is the version I have still valid?" — server responds 304 Not Modified with no body if yes.

The Richardson Maturity Model

Leonard Richardson described how "RESTful" a given API is on a four-step ladder. Most "REST" APIs are at level 2 — that's fine.

HATEOAS — the academic constraint nobody follows

Level 3 says responses should include links the client can follow:

{
  "id": 42,
  "status": "paid",
  "_links": {
    "self":    { "href": "/orders/42" },
    "refund":  { "href": "/orders/42/refund" },
    "invoice": { "href": "/orders/42/invoice" }
  }
}

Idea: clients discover capabilities at runtime, not by reading docs. In practice, almost no public API does this. Clients are written against API docs, not by exploring links. Spring HATEOAS exists; it's mostly used in enterprise systems with strict requirements. Don't worry about HATEOAS for interviews — recognize the term, move on.

How Spring expresses REST

@RestController
@RequestMapping("/users")
public class UserController {

  private final UserService userService;

  @GetMapping
  public List<UserDto> list() { return userService.findAll(); }

  @GetMapping("/{id}")
  public UserDto get(@PathVariable Long id) { return userService.findById(id); }

  @PostMapping
  @ResponseStatus(HttpStatus.CREATED)
  public UserDto create(@Valid @RequestBody CreateUserRequest req) { return userService.create(req); }

  @PatchMapping("/{id}")
  public UserDto update(@PathVariable Long id, @RequestBody PatchUserRequest req) { return userService.patch(id, req); }

  @DeleteMapping("/{id}")
  @ResponseStatus(HttpStatus.NO_CONTENT)
  public void delete(@PathVariable Long id) { userService.delete(id); }
}

Every line maps cleanly to REST conventions: @GetMapping, plural collection in path, @PathVariable for the resource id, 201 Created on POST, 204 No Content on DELETE. Spring makes the right thing easy.

The five most common REST mistakes

API versioning — the unavoidable conversation

You'll change your API. Clients depend on it. How do you make changes without breaking them?

REST vs. GraphQL vs. gRPC — the lay of the land

For your career trajectory: master REST. It's the lingua franca. The other two come up only when a specific need arises.

End of Day 13. Tomorrow: JSP — a brief historical tour, the bridge to today's frontend separation.