Design de APIs REST

REST (Representational State Transfer) é um estilo arquitetural — não um protocolo — definido por Roy Fielding em sua tese de doutorado de 2000¹. Uma API web que segue as restrições do REST é chamada de API RESTful. O REST usa o HTTP como protocolo de transferência e aproveita a semântica já existente dos métodos HTTP, dos códigos de status e dos cabeçalhos.

Restrições do REST

Recursos e URIs

Um recurso é um substantivo — algo que a API expõe. URIs identificam recursos, não ações.

Convenções de URI

• Use substantivos no plural para coleções: /orders, /products, /users
• Use letras minúsculas com hífens: /order-items, e não /orderItems
• Aninhe para expressar posse: /users/7/orders — pedidos que pertencem ao usuário 7
• Limite a profundidade do aninhamento a 2–3 níveis; evite /users/7/orders/42/items/3/reviews

Métodos HTTP

Idempotente — executar a mesma requisição várias vezes tem o mesmo efeito que executá-la uma vez. PUT /orders/42 com o mesmo corpo pode ser repetido com segurança; POST /orders criaria duplicatas.

Seguro — a requisição não altera o estado do servidor. GET e HEAD são seguros; todos os outros não são.

Códigos de status HTTP

Use o código certo — clientes e intermediários dependem deles.

2xx — Sucesso

4xx — Erro do cliente

5xx — Erro do servidor

Formato de requisição e resposta

Requisição

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

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

Resposta

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"
}

Resposta de erro

Padronize as respostas de erro para que os clientes possam tratá-las de forma genérica:

{
  "status": 422,
  "error": "Validation failed",
  "message": "Product 101 is out of stock",
  "path": "/orders",
  "timestamp": "2026-04-28T14:30:00Z"
}

O @ControllerAdvice + @ExceptionHandler do Spring Boot é a forma padrão de produzir respostas de erro consistentes.

Paginação e filtragem

Coleções nunca devem retornar resultados ilimitados. Use parâmetros de consulta (query parameters) para paginação e filtragem:

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

A resposta deve incluir metadados de paginação:

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

Versionamento

APIs evoluem. Quando uma mudança incompatível (breaking change) é inevitável, versione a API para que os clientes existentes não quebrem:

O versionamento pelo caminho da URI é a escolha mais comum em microsserviços. Incrementos de versão principal (v1 → v2) sinalizam mudanças incompatíveis; melhorias menores são adicionadas sem mudar a versão.

Referência rápida em Spring Boot

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping
    public List<OrderOut> listOrders() { ... }

    @GetMapping("/{id}")
    public OrderOut getOrder(@PathVariable Long id) { ... }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderOut createOrder(@RequestBody @Valid OrderIn in) { ... }

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