API REST bem desenhada: nomes, status codes e paginação que não confundem ninguém

Uma API é um produto para desenvolvedores — os do seu time, os do app e os de parceiros. Quando ela é confusa, cada integração vira uma investigação. Algumas convenções simples evitam semanas de retrabalho.

Recursos no plural, verbos no método

• GET /pedidos lista, GET /pedidos/123 detalha.
• POST /pedidos cria, PATCH /pedidos/123 altera parcialmente, DELETE /pedidos/123 remove.
• Nada de /criarPedido ou /getPedidos: o verbo já está no método HTTP.

Status codes que dizem a verdade

• 200/201 sucesso e criação; 204 quando não há corpo.
• 400 requisição malformada; 401 não autenticado; 403 sem permissão; 404 não existe.
• 422 dados inválidos; 429 limite excedido (Rate limiting em Node.js: como proteger suas APIs contra sobrecarga e abusos sem afetar a UX).
• 500 erro do servidor — nunca use 200 com "success": false.

Respostas de erro num formato único, como em Tratamento global de erros no Node.js: respostas consistentes e logs úteis.

Toda lista é paginada

Sem paginação, a lista que hoje tem 50 itens terá 50 mil daqui a dois anos — e a rota vai cair. Escolher entre página numerada e cursor tem consequências: veja Paginação por cursor vs. offset: quando a lista começa a ficar lenta.

Filtros e ordenação previsíveis

GET /pedidos?status=pago&ordem=-criadoEm é fácil de entender e de cachear.

Datas em ISO 8601 com fuso

2026-05-10T14:30:00Z, nunca "10/05/2026 14:30" — o motivo está em Datas e fusos horários: o bug que aparece às 21h.

Pensando no futuro

Mudanças que quebram contrato precisam de versão (Versionamento de API: mudar sem quebrar o app de ninguém). E, se REST não encaixa no seu caso, vale comparar com GraphQL ou REST: escolha pelo problema, não pela moda.

A We Codex desenha e constrói APIs em Node.js para sistemas web e apps. Fale com a gente.