REST API Design

Your team must publish the store's Product API: create, list, fetch and delete products. Two other teams (the web front-end and the order service) will call it without ever reading your code. Which URLs should exist? Which HTTP method creates a product? What does the client receive when the product does not exist, or when the request times out and it tries again? REST gives a shared set of answers, so that every API in the platform behaves the same way.

REST (Representational State Transfer) is an architectural style — not a protocol — defined by Roy Fielding in his 2000 doctoral dissertation¹. A web API that follows REST constraints is called a RESTful API. REST uses HTTP as its transfer protocol and leverages the existing semantics of HTTP methods, status codes, and headers².

Resources and representations

Two words carry the whole idea:

• A resource is anything the API exposes that has a name: a product, the collection of all products, the orders of one user. Each resource is identified by a URI (Uniform Resource Identifier), e.g. /products/0195abfb-7074-73a9-9d26-b4b9fbaab0a8.
• A representation is a snapshot of the resource's state in some format — usually a JSON document. The client never touches the resource itself (a row in Postgres); it reads and sends representations of it. That is the "Representational State Transfer" of the name.

{
  "id": "0195abfb-7074-73a9-9d26-b4b9fbaab0a8",
  "name": "Tomato",
  "price": 10.12,
  "unit": "kg"
}

The Content-Type header says which format the body is in (application/json); the Accept header says which formats the client wants back.

REST constraints

Fielding defined REST as a set of constraints. An API that respects them gets the properties the Web is known for: scalability, independent evolution of client and server, and intermediaries (caches, gateways) that work without knowing the application.

In the course's platform, Stateless and Layered System are what make horizontal scaling possible: because no replica keeps a session, the load balancer of Hands-on 7 can send each request to any gateway instance, and the client cannot tell Nginx, the gateway and the service apart.

Resources and URIs

A resource is a noun — a thing the API exposes. URIs identify resources, not actions.

URI conventions

• Use plural nouns for collections: /orders, /products, /users
• Use lowercase with hyphens: /order-items not /orderItems
• Nest to express ownership: /users/7/orders — orders belonging to user 7
• Limit nesting depth to 2–3 levels; avoid /users/7/orders/42/items/3/reviews
• Use query parameters for things that are not identity: filtering, sorting, pagination (/orders?status=PENDING)

HTTP methods

Safe — the request does not change server state. GET, HEAD and OPTIONS are safe; POST, PUT, PATCH and DELETE are not. Because they are safe, caches and crawlers may call them freely.

Idempotent — calling the same request multiple times has the same effect on the server as calling it once. PUT /orders/42 with the same body can be retried freely; POST /orders would create duplicates. PATCH is not guaranteed to be idempotent: {"op": "increment", "field": "quantity"} changes the result on every call.

Making POST safe to retry: idempotency keys

Networks lose messages. If the client sends POST /orders and the response never arrives, it cannot tell whether the order was created (see Distributed Systems). Retrying may create a duplicate order; not retrying may lose it.

The standard solution is an idempotency key: the client generates a unique id (a UUID) per logical operation and sends it in a header; the server remembers which keys it has already processed and, on a repeat, returns the stored result instead of executing again⁴⁵.

sequenceDiagram
    participant C as Client
    participant O as Order Service
    C->>O: POST /orders, Idempotency-Key k1
    O->>O: create order 42, remember k1 → 42
    O--xC: 201 Created (response lost)
    Note over C: timeout, retry with the SAME key
    C->>O: POST /orders, Idempotency-Key k1
    O->>O: k1 already processed
    O-->>C: 201 Created, order 42 (no duplicate)

The server stores the key with the result (for example, in a table with a unique constraint on the key, or in Redis with an expiry). Payment providers such as Stripe use exactly this mechanism. Retries, timeouts and backoff are covered in Resilience Patterns.

HTTP status codes

Use the right code — clients and intermediaries rely on them³. The first digit gives the class: 2xx success, 3xx redirection, 4xx the client did something wrong (do not retry unchanged), 5xx the server failed (a retry may succeed).

2xx — Success

4xx — Client error

5xx — Server error

In a microservice platform the gateway codes matter: a 502 or 504 returned to the browser usually means "the gateway is fine, the service behind it is not" — the first clue when debugging.

Request and response format

Request

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

{
  "customerId": 7,
  "items": [
    { "productId": 101, "quantity": 2 }
  ]
}

Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: /orders/42

{
  "id": 42,
  "customerId": 7,
  "status": "PENDING",
  "total": { "amount": 59.90, "currency": "BRL" },
  "createdAt": "2026-04-28T14:30:00Z"
}

Conventions worth keeping across all services: camelCase field names, dates in ISO 8601 with time zone (2026-04-28T14:30:00Z), money with an explicit currency, and ids as opaque strings (the course uses UUIDs).

Error response

Standardise error responses so clients can handle them generically. The IETF standard for this is Problem Details for HTTP APIs (RFC 9457⁶), served with the media type application/problem+json:

{
  "type": "https://store.example.com/problems/out-of-stock",
  "title": "Product out of stock",
  "status": 422,
  "detail": "Product 101 is out of stock",
  "instance": "/orders"
}

Spring Boot's @ControllerAdvice / @RestControllerAdvice + @ExceptionHandler is the standard way to produce consistent error responses, and Spring's ProblemDetail class produces the RFC 9457 shape:

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ProblemDetail handleNotFound(ProductNotFoundException e) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, e.getMessage());
        problem.setTitle("Product not found");
        return problem; // serialised as application/problem+json
    }
}

Setting spring.mvc.problemdetails.enabled: true makes Spring MVC's own errors (for example, a failed @Valid) use the same format.

Pagination and filtering

Collections should never return unbounded results. Use query parameters for pagination and filtering:

GET /orders?page=2&size=20&sort=createdAt,desc
GET /orders?status=PENDING&customerId=7

Offset pagination asks the database for OFFSET 40 LIMIT 20: the database still reads and discards the first 40 rows, and if a row is inserted meanwhile, the client sees an item twice. A cursor encodes "the last item I saw" (e.g. its id) and the query becomes WHERE id > :last ORDER BY id LIMIT 20, which uses the index and is not affected by inserts.

The response should include pagination metadata. Spring Data's Pageable reads page, size and sort automatically (pages are 0-based, so page=2 is the third page), and its PagedModel serialises as:

{
  "content": [...],
  "page": { "size": 20, "number": 2, "totalElements": 150, "totalPages": 8 }
}

Versioning

APIs evolve. The first question is whether a change is breaking — whether an existing client, unchanged, would stop working:

Compatible changes rely on clients being tolerant readers: they ignore fields they do not know. (Jackson in Spring Boot ignores unknown properties by default; do not turn that off in clients.)

When a breaking change is unavoidable, version the API so existing clients are not broken:

URI path versioning is the most common choice for microservices. Major version increments (v1 → v2) signal breaking changes; minor improvements are added without a version bump. Run both versions side by side, announce a deprecation date, and remove v1 only when its traffic has gone — the Sunset header (RFC 8594) tells clients when an endpoint will disappear.

Spring Boot quick reference

The Product API of the exercise, with the status codes chosen above:

@RestController
@RequestMapping("/products")
public class ProductResource {

    @Autowired
    private ProductService productService;

    @GetMapping
    public ResponseEntity<List<ProductOut>> findAll() {
        return ResponseEntity.ok(productService.findAll());               // 200
    }

    @GetMapping("/{id}")
    public ResponseEntity<ProductOut> findById(@PathVariable String id) {
        return ResponseEntity.ok(productService.findById(id));            // 200, or 404 via the advice
    }

    @PostMapping
    public ResponseEntity<ProductOut> create(@RequestBody @Valid ProductIn in) {
        ProductOut created = productService.create(in);
        return ResponseEntity
            .created(URI.create("/products/" + created.id()))             // 201 + Location
            .body(created);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable String id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();                        // 204
    }
}

@ResponseStatus(HttpStatus.CREATED) on a method also returns 201, but it cannot set the Location header; ResponseEntity.created(uri) sets both. @Valid triggers Bean Validation on the DTO (@NotBlank, @Positive…) and turns a violation into 400 Bad Request.

Key takeaways

• URIs name resources (plural nouns); the HTTP method says what to do; clients exchange representations (JSON).
• GET is safe; GET, PUT and DELETE are idempotent; POST is neither — make it retry-safe with an idempotency key.
• Return the precise status code (201 + Location, 204, 401 vs 403, 422, 502/504) and errors as Problem Details.
• Paginate every collection; prefer cursors for large or fast-changing tables.
• Add, do not remove: compatible changes need no version; breaking ones need /v2/ and a deprecation period.

Connections

• Implement these conventions: Hands-on 1 — CRUD, Product API, Order API.
• 401 and 403 in practice: Hands-on 3 — Security and Security.
• Retries and 429/503: Resilience Patterns.
• Document the contract: OpenAPI & Swagger.