REST Resource Design

In one line

Model your API around resources (nouns) and use HTTP methods as the verbs. Consistent naming, status codes, and error shapes make an API predictable, and predictable APIs get integrated faster and break less.

0/7 · 0%

Think of it like this

A well-organised library. Books are found by predictable shelf codes (/authors/7/books), and every desk uses the same forms. You can find a book in a library you've never visited because the conventions are shared. REST conventions do the same for APIs.

Key ideas

01
RESOURCES are nouns, plural, hierarchical where there's real ownership: /users/42, /users/42/orders, /orders/9001/items. Avoid verbs in paths (/getOrders, /createUser); the HTTP method is the verb. For actions that aren't CRUD, use a sub-resource (POST /orders/9001/cancellation) or a clearly named action endpoint.
02
Methods map to intent: GET read (safe, cacheable), POST create or trigger, PUT replace, PATCH partial update, DELETE remove. Status codes carry meaning: 201 + Location header on create, 204 when there's no body, 400 for invalid input, 401/403 for identity and permission, 404, 409 for conflicts (duplicate, version mismatch), 422 for semantically invalid data, 429 for rate limits.
03
ONE ERROR SHAPE for the whole API, ideally RFC 9457 'Problem Details': {"type": ".../out-of-stock", "title": "Item out of stock", "status": 409, "detail": "Only 2 left", "instance": "/orders/9001"}. Clients can then handle errors generically. Never leak stack traces or SQL errors.
04
Design from the CLIENT's use cases, not your database tables. If the mobile home screen needs products + prices + stock, don't force three round-trips; consider a purpose-built endpoint or embedding (?include=stock). Document the contract with OpenAPI and generate clients and tests from it.

Java / Spring map

→
Spring's ProblemDetail class and @ControllerAdvice + @ExceptionHandler produce RFC 9457 errors consistently across every controller; springdoc-openapi generates the OpenAPI document from your controllers.

Code & diagrams

ApiErrors.javajava

One place that turns exceptions into consistent Problem Details responses.

@RestControllerAdvice
class ApiErrors {
  @ExceptionHandler(OutOfStockException.class)
  ProblemDetail outOfStock(OutOfStockException e) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, e.getMessage());
    pd.setType(URI.create("https://api.shop.com/problems/out-of-stock"));
    pd.setTitle("Item out of stock");
    pd.setProperty("available", e.available());
    return pd;
  }
}

Explain without notes

Why should paths be nouns and not verbs?

Practice

Design the REST API for a ride-hailing app's trips: request a ride, see its status, cancel it, rate the driver.

Trade-offs

↔
Purely resource-oriented APIs are predictable but can cause chatty clients; purpose-built endpoints (Backend-for-Frontend) reduce round-trips at the cost of more endpoints to maintain.

Run it in production

You've designed it. Now build, operate, and break the same idea hands-on in the DevOps courses:

Networking · HTTP on the wire

Methods, status codes, and headers in raw curl -v output.

Completion checklist

My paths are nouns, methods carry the intent
My API uses one consistent error format
I can design an API from client use cases

Back to phase

Command Palette