Design de APIs REST

Uma API é uma interface para pessoas

Quem consome uma API é um programa, mas quem escreve esse programa é uma pessoa. Ela lê a documentação, tenta um pedido, interpreta a resposta e escreve o código de integração. Uma API bem desenhada é aquela em que essa pessoa adivinha certo: depois de usar duas rotas, ela prevê como a terceira funciona.

O estilo REST, apresentado no tópico de estilos de API, organiza a API em torno de recursos manipulados pelos métodos do HTTP. Este tópico trata das decisões de desenho dentro desse estilo.

Recursos e endereços

Um recurso é qualquer coisa que a API expõe: um pedido, um cliente, os itens de um pedido. Cada recurso tem um endereço, e o endereço usa substantivos. A ação vem do método.

Os erros mais comuns de endereço:

Ações que não são criar, ler, alterar ou remover

Nem tudo cabe nos quatro verbos. Cancelar um pedido, reenviar um e-mail, aprovar um reembolso. A forma mais consistente é tratar a ação como a criação de um recurso:

POST /pedidos/981/cancelamento
Content-Type: application/json

{ "motivo": "cliente desistiu" }

O cancelamento passa a ser algo que existe, com data, motivo e quem o fez, e pode ser consultado depois em GET /pedidos/981/cancelamento.

Códigos de status

O tópico de HTTP apresenta os códigos de status. No desenho da API, o importante é usar cada um de forma previsível:

A diferença entre 400 e 422 costuma gerar debate. Uma convenção comum, usada nos exemplos deste tópico: 400 quando o pedido não pode nem ser lido (JSON malformado), 422 quando foi lido, mas os dados não passam na validação.

Erros num formato único

A parte mais negligenciada de uma API é o formato dos erros. Cada rota inventando o seu cria clientes cheios de casos especiais:

{ "erro": "pedido não encontrado" }
{ "message": "Invalid quantity", "code": 4001 }
{ "success": false, "errors": ["clienteId is required"] }

O padrão Problem Details (RFC 9457) define um formato único, com o tipo de conteúdo application/problem+json:

{
  "type": "https://api.loja.com.br/erros/dados-invalidos",
  "title": "Os dados enviados são inválidos",
  "status": 422,
  "errors": {
    "clienteId": "obrigatório",
    "itens[0].quantidade": "inteiro maior que zero"
  }
}

Implementamos esse formato nas cinco linguagens e executamos quatro delas. TypeScript, Python, Go e C# responderam com application/problem+json e status 422 aos dados inválidos e 400 ao JSON malformado. Os detalhes variaram: o C# coloca as mensagens em listas e acrescenta um traceId; o FastAPI usa as mensagens de validação do Pydantic, em inglês. O nível Implementação mostra a comparação completa.

Representações

A última linha merece atenção. Devolver a entidade do banco diretamente, em vez de um formato desenhado para a API, expõe campos que deveriam ser internos e prende o contrato da API ao esquema do banco: uma coluna renomeada quebra os clientes.

Por que isso importa quando a IA escreve o código

Um assistente gera rotas que funcionam isoladamente, e cada uma pode sair com um estilo diferente:

• Verbos nos endereços (/getPedido, /cancelarPedido) e ações em GET.
• 200 para tudo, com o erro dentro do corpo.
• Um formato de erro diferente em cada rota, ou o formato padrão do framework misturado com um próprio.
• A entidade do banco devolvida inteira, com campos internos.
• 403 para recursos de outros usuários, revelando quais identificadores existem.

O próximo nível compara as decisões de desenho que mais aparecem e quando escolher cada lado.