API

Replace everything behind it

• None — as long as the contract is respected.
• An API defines the operations, their inputs and outputs — and hides the implementation.
• In the hands-on: module account = the contract (AccountController + AccountIn/AccountOut); account-service = the private implementation.
• Changing a DTO is changing the contract: never return the JPA model.

Types of APIs

Same question, three shapes: GET /products/42 · rpc GetProduct(GetProductRequest) · query { product(id: "42") { name price } }

How RESTful? The Richardson model

Resources are nouns

Good	Bad
GET /orders	GET /getOrders
POST /orders	POST /createOrder
GET /orders/42	GET /order?id=42
DELETE /orders/42	POST /deleteOrder/42

• Plural nouns: /orders, /products
• Lowercase with hyphens: /order-items
• Nest for ownership: /users/7/orders
• At most 2–3 levels of nesting
• Filters, sort, pages → query parameters

HTTP methods

Method	Idempotent	Safe	Use
GET			read a resource or collection
POST			create — the server assigns the ID
PUT			replace the whole resource
PATCH			partial update
DELETE			remove

• Safe: does not change server state. Idempotent: repeating it has the same effect as calling once.
• A second DELETE /products/42 returns 404 — still idempotent: the state is the same.

Retrying a POST: idempotency keys

• The client sends a unique Idempotency-Key (a UUID) per logical operation.
• The server stores processed keys with their result.
• A retry with the same key returns the stored result — no duplicate.
• Same mechanism as Stripe's payment API; retries and backoff → Resilience Patterns.

Request and response

POST /products HTTP/1.1
Content-Type: application/json

{
  "name": "Tomato",
  "price": 10.12,
  "unit": "kg"
}

HTTP/1.1 201 Created
Location: /products/0195abfb-...

{
  "id": "0195abfb-...",
  "name": "Tomato",
  "price": 10.12,
  "unit": "kg"
}

Spring: ResponseEntity.created(uri).body(out) sets both 201 and Location; @ResponseStatus(CREATED) cannot set the header.

Errors with a standard shape: Problem Details

RFC 9457, 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"
}

In Spring Boot: @RestControllerAdvice + @ExceptionHandler returning a ProblemDetail; spring.mvc.problemdetails.enabled: true for the framework's own errors.

Pagination and versioning

Breaking or not?

Takeaways

1. An API is a contract: consumers depend on it, never on the implementation (account vs account-service).
2. Most APIs live at Richardson level 2: resources + HTTP verbs + status codes.
3. Know what is safe (GET) and idempotent (GET, PUT, DELETE); make POST retry-safe with an idempotency key.
4. Return the right status code and errors as Problem Details.
5. Paginate collections; prefer compatible changes, version breaking ones with /v2/.
6. An OpenAPI document describes the contract; springdoc generates it and Swagger UI from the code — keep it off in production.