API

Troque tudo o que está por trás

• Nenhum — desde que o contrato seja respeitado.
• Uma API define as operações, suas entradas e saídas — e esconde a implementação.
• No hands-on: módulo account = o contrato (AccountController + AccountIn/AccountOut); account-service = a implementação privada.
• Mudar um DTO é mudar o contrato: nunca retorne o modelo JPA.

Tipos de APIs

Mesma pergunta, três formas: GET /products/42 · rpc GetProduct(GetProductRequest) · query { product(id: "42") { name price } }

Quão RESTful? O modelo de Richardson

Recursos são substantivos

Bom	Ruim
GET /orders	GET /getOrders
POST /orders	POST /createOrder
GET /orders/42	GET /order?id=42
DELETE /orders/42	POST /deleteOrder/42

• Substantivos no plural: /orders, /products
• Minúsculas com hífens: /order-items
• Aninhe para indicar posse: /users/7/orders
• No máximo 2–3 níveis de aninhamento
• Filtros, ordenação, páginas → parâmetros de query

Métodos HTTP

Método	Idempotente	Seguro	Uso
GET			ler um recurso ou uma coleção
POST			criar — o servidor atribui o ID
PUT			substituir o recurso inteiro
PATCH			atualização parcial
DELETE			remover

• Seguro: não muda o estado do servidor. Idempotente: repetir tem o mesmo efeito que chamar uma vez.
• Um segundo DELETE /products/42 retorna 404 — ainda idempotente: o estado é o mesmo.

Repetindo um POST: chaves de idempotência

• O cliente envia uma Idempotency-Key única (um UUID) por operação lógica.
• O servidor armazena as chaves processadas junto com o resultado.
• Uma repetição com a mesma chave devolve o resultado armazenado — sem duplicata.
• É o mesmo mecanismo da API de pagamentos da Stripe; retries e backoff → Padrões de Resiliência.

Requisição e resposta

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) define tanto o 201 quanto o Location; @ResponseStatus(CREATED) não consegue definir o cabeçalho.

Erros com formato padrão: 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"
}

No Spring Boot: @RestControllerAdvice + @ExceptionHandler retornando um ProblemDetail; spring.mvc.problemdetails.enabled: true para os erros do próprio framework.

Paginação e versionamento

Incompatível ou não?

Pontos-chave

1. Uma API é um contrato: os consumidores dependem dele, nunca da implementação (account vs account-service).
2. A maioria das APIs está no nível 2 de Richardson: recursos + verbos HTTP + códigos de status.
3. Saiba o que é seguro (GET) e idempotente (GET, PUT, DELETE); torne o POST seguro para repetir com uma chave de idempotência.
4. Retorne o código de status certo e os erros como Problem Details.
5. Pagine as coleções; prefira mudanças compatíveis e versione as incompatíveis com /v2/.
6. Um documento OpenAPI descreve o contrato; o springdoc gera o documento e o Swagger UI a partir do código — desligue-o em produção.