Design de APIs REST: as boas práticas que evitam dor de cabeça para você e seus consumidores

Uma API bem desenhada é um prazer de consumir. Uma API mal desenhada é uma fonte constante de frustração, bugs e perguntas de suporte. A maioria dos desenvolvedores aprende a criar APIs que funcionam — retornam os dados certos quando chamadas corretamente. Mas poucos pensam sistematicamente em como a API será consumida por outros desenvolvedores, em como comunicar erros de forma útil, em como versionar sem quebrar clientes existentes. Essas são as habilidades que diferenciam bons designers de API.

URLs que descrevem recursos, não ações

REST usa substantivos para URLs e verbos HTTP para ações. GET /usuarios retorna lista de usuários. POST /usuarios cria um usuário. GET /usuarios/42 retorna o usuário 42. PUT /usuarios/42 atualiza o usuário 42 completo. PATCH /usuarios/42 atualiza parcialmente. DELETE /usuarios/42 remove. A URL nunca deve ter verbo: não /getUsuarios, não /criarUsuario, não /deletarUsuario. O verbo HTTP já diz o que fazer — a URL diz com o quê.

Recursos aninhados fazem sentido quando existe uma relação de containment clara: GET /pedidos/15/itens retorna os itens do pedido 15. Mas evite aninhamento profundo demais — /usuarios/42/pedidos/15/itens/3/imagens é um URL difícil de ler e de manter. Se a relação se torna complexa, considere um endpoint de nível superior com parâmetros de filtro.

Códigos HTTP: use-os com precisão

Cada código de status HTTP tem um significado específico — usá-los corretamente é uma forma de comunicação com quem consome a API. 200 OK para sucesso com corpo de resposta. 201 Created para criação bem-sucedida (com header Location apontando para o novo recurso). 204 No Content para DELETE bem-sucedido. 400 Bad Request para erros de validação do input (dados inválidos enviados pelo cliente). 401 Unauthorized para falta de autenticação. 403 Forbidden para autenticado mas sem permissão. 404 Not Found para recurso inexistente. 422 Unprocessable Entity para quando os dados são sintaticamente corretos mas semanticamente inválidos. 500 Internal Server Error para erros não esperados no servidor.

O erro mais comum: retornar sempre 200 com um campo de erro no body — {"status": "error", "message": "..."}. Isso força quem consome a API a parsear o body para descobrir se deu certo. Com status codes corretos, response.ok (JavaScript) ou uma verificação de 2xx é suficiente para saber se foi sucesso.

Mensagens de erro úteis

Erros de validação devem ser detalhados: não apenas “dados inválidos”, mas quais campos, por quê, e o que seria válido. Um formato padronizado de erro facilita o consumo pelos clientes: um objeto com campo code (código de erro legível por máquina), message (mensagem legível por humano) e details (array de erros específicos por campo) é o padrão adotado por APIs de grandes empresas. O desenvolvedor que integra sua API deve conseguir exibir um feedback útil ao usuário final a partir da resposta de erro — sem precisar parsear strings de mensagem.

Versioning: não quebre quem já usa sua API

APIs públicas ou consumidas por múltiplos clientes precisam de estratégia de versionamento. A abordagem mais comum e direta: versão na URL (/api/v1/usuarios, /api/v2/usuarios). Quando você faz mudanças breaking (remove campo, muda nome, altera tipo), lança v2 mantendo v1 operacional por um período de deprecação anunciado. Avoid versionamento por header (Accept: application/vnd.empresa.v2+json) — é tecnicamente mais “REST puro” mas muito menos prático para desenvolvedores que precisam testar no browser ou no cURL.

Paginação e filtros consistentes

Toda API que retorna coleções precisa de paginação — retornar 50.000 registros em uma requisição é impraticável. Use parâmetros padronizados: ?page=2&per_page=20 ou ?offset=40&limit=20. A resposta inclui metadados: total de registros, página atual, total de páginas, links para próxima e página anterior. Filtros por query string: ?status=ativo&cidade=SP&sort=nome&order=asc. Documente todos esses parâmetros no OpenAPI/Swagger — uma especificação é muito mais útil do que documentação em texto livre para quem vai integrar.