Design de APIs REST

Seu time precisa publicar a Product API da loja: criar, listar, buscar e excluir produtos. Dois outros times (o front-end web e o serviço de pedidos) vão chamá-la sem nunca ler o seu código. Quais URLs devem existir? Qual método HTTP cria um produto? O que o cliente recebe quando o produto não existe, ou quando a requisição estoura o timeout e ele tenta de novo? O REST oferece um conjunto compartilhado de respostas, para que todas as APIs da plataforma se comportem da mesma forma.

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, códigos de status e cabeçalhos HTTP².

Recursos e representações

Duas palavras carregam a ideia toda:

• Um recurso é qualquer coisa que a API expõe e que tem um nome: um produto, a coleção de todos os produtos, os pedidos de um usuário. Cada recurso é identificado por uma URI (Uniform Resource Identifier), por exemplo /products/0195abfb-7074-73a9-9d26-b4b9fbaab0a8.
• Uma representação é um retrato do estado do recurso em algum formato — geralmente um documento JSON. O cliente nunca toca no recurso em si (uma linha no Postgres); ele lê e envia representações dele. É esse o "Representational State Transfer" (transferência de estado representacional) do nome.

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

O cabeçalho Content-Type diz em que formato o corpo está (application/json); o cabeçalho Accept diz quais formatos o cliente quer receber de volta.

Restrições do REST

Fielding definiu o REST como um conjunto de restrições. Uma API que as respeita ganha as propriedades pelas quais a Web é conhecida: escalabilidade, evolução independente de cliente e servidor, e intermediários (caches, gateways) que funcionam sem conhecer a aplicação.

Na plataforma do curso, Stateless e Layered System são o que torna possível a escalabilidade horizontal: como nenhuma réplica guarda sessão, o balanceador de carga do Hands-on 7 pode enviar cada requisição para qualquer instância do gateway, e o cliente não consegue distinguir o Nginx, o gateway e o serviço.

Recursos e URIs

Um recurso é um substantivo — uma coisa 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 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 o aninhamento a 2–3 níveis; evite /users/7/orders/42/items/3/reviews
• Use parâmetros de consulta (query parameters) para o que não é identidade: filtragem, ordenação, paginação (/orders?status=PENDING)

Métodos HTTP

Seguro (safe) — a requisição não altera o estado do servidor. GET, HEAD e OPTIONS são seguros; POST, PUT, PATCH e DELETE não são. Por serem seguros, caches e crawlers podem chamá-los livremente.

Idempotente — enviar a mesma requisição várias vezes tem o mesmo efeito no servidor que enviá-la uma vez. PUT /orders/42 com o mesmo corpo pode ser repetido livremente; POST /orders criaria duplicatas. PATCH não tem idempotência garantida: {"op": "increment", "field": "quantity"} muda o resultado a cada chamada.

Tornando o POST seguro para repetir: chaves de idempotência

Redes perdem mensagens. Se o cliente envia POST /orders e a resposta nunca chega, ele não tem como saber se o pedido foi criado (veja Sistemas Distribuídos). Repetir pode criar um pedido duplicado; não repetir pode perdê-lo.

A solução padrão é uma chave de idempotência (idempotency key): o cliente gera um id único (um UUID) por operação lógica e o envia em um cabeçalho; o servidor lembra quais chaves já processou e, em uma repetição, devolve o resultado armazenado em vez de executar de novo⁴⁵.

sequenceDiagram
    participant C as Cliente
    participant O as Serviço de Pedidos
    C->>O: POST /orders, Idempotency-Key k1
    O->>O: cria o pedido 42, guarda k1 → 42
    O--xC: 201 Created (resposta perdida)
    Note over C: timeout, retry com a MESMA chave
    C->>O: POST /orders, Idempotency-Key k1
    O->>O: k1 já processada
    O-->>C: 201 Created, pedido 42 (sem duplicata)

O servidor armazena a chave junto com o resultado (por exemplo, em uma tabela com restrição de unicidade na chave, ou no Redis com expiração). Provedores de pagamento como a Stripe usam exatamente esse mecanismo. Retries, timeouts e backoff são tratados em Padrões de Resiliência.

Códigos de status HTTP

Use o código certo — clientes e intermediários dependem deles³. O primeiro dígito indica a classe: 2xx sucesso, 3xx redirecionamento, 4xx o cliente fez algo errado (não repita sem alterar), 5xx o servidor falhou (uma nova tentativa pode dar certo).

2xx — Sucesso

4xx — Erro do cliente

5xx — Erro do servidor

Em uma plataforma de microsserviços, os códigos de gateway importam: um 502 ou 504 devolvido ao navegador geralmente significa "o gateway está bem, o serviço por trás dele não" — a primeira pista na hora de depurar.

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

Convenções que vale manter em todos os serviços: nomes de campos em camelCase, datas em ISO 8601 com fuso horário (2026-04-28T14:30:00Z), valores monetários com moeda explícita e ids como strings opacas (o curso usa UUIDs).

Resposta de erro

Padronize as respostas de erro para que os clientes possam tratá-las de forma genérica. O padrão da IETF para isso é o Problem Details for HTTP APIs (RFC 9457⁶), servido com o 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, @ControllerAdvice / @RestControllerAdvice + @ExceptionHandler é a forma padrão de produzir respostas de erro consistentes, e a classe ProblemDetail do Spring produz o formato da RFC 9457:

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

Definir spring.mvc.problemdetails.enabled: true faz com que os próprios erros do Spring MVC (por exemplo, um @Valid que falhou) usem o mesmo formato.

Paginação e filtragem

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

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

A paginação por offset pede ao banco de dados OFFSET 40 LIMIT 20: o banco ainda lê e descarta as primeiras 40 linhas e, se uma linha for inserida nesse meio-tempo, o cliente vê um item duas vezes. Um cursor codifica "o último item que eu vi" (por exemplo, o id dele) e a consulta passa a ser WHERE id > :last ORDER BY id LIMIT 20, que usa o índice e não é afetada por inserções.

A resposta deve incluir metadados de paginação. O Pageable do Spring Data lê page, size e sort automaticamente (as páginas começam em 0, então page=2 é a terceira página), e o seu PagedModel é serializado assim:

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

Versionamento

APIs evoluem. A primeira pergunta é se uma mudança é incompatível (breaking) — se um cliente existente, sem alterações, deixaria de funcionar:

As mudanças compatíveis contam com clientes que sejam leitores tolerantes (tolerant readers): eles ignoram os campos que não conhecem. (O Jackson, no Spring Boot, ignora propriedades desconhecidas por padrão; não desligue isso nos clientes.)

Quando uma mudança incompatível é inevitável, versione a API para que os clientes existentes não quebrem:

Versionar pelo caminho da URI é a escolha mais comum em microsserviços. Incrementos de versão major (v1 → v2) sinalizam mudanças incompatíveis; melhorias menores são adicionadas sem mudar a versão. Mantenha as duas versões rodando lado a lado, anuncie uma data de descontinuação e remova a v1 apenas quando o tráfego dela tiver acabado — o cabeçalho Sunset (RFC 8594) informa aos clientes quando um endpoint vai desaparecer.

Referência rápida em Spring Boot

A Product API do exercício, com os códigos de status escolhidos acima:

@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) em um método também retorna 201, mas não consegue definir o cabeçalho Location; ResponseEntity.created(uri) define os dois. @Valid dispara a Bean Validation no DTO (@NotBlank, @Positive…) e transforma uma violação em 400 Bad Request.

Pontos-chave

• URIs nomeiam recursos (substantivos no plural); o método HTTP diz o que fazer; os clientes trocam representações (JSON).
• GET é seguro; GET, PUT e DELETE são idempotentes; POST não é nem um nem outro — torne-o seguro para repetir com uma chave de idempotência.
• Retorne o código de status exato (201 + Location, 204, 401 vs 403, 422, 502/504) e os erros como Problem Details.
• Pagine toda coleção; prefira cursores para tabelas grandes ou que mudam rápido.
• Adicione, não remova: mudanças compatíveis não precisam de versão; as incompatíveis precisam de /v2/ e de um período de descontinuação.

Conexões

• Implemente estas convenções: Hands-on 1 — CRUD, Product API, Order API.
• 401 e 403 na prática: Hands-on 3 — Segurança e Segurança.
• Retries e 429/503: Padrões de Resiliência.
• Documente o contrato: OpenAPI & Swagger.