Pular para o conteúdo

API REST: boas práticas de nomes, status codes e paginação

Rotas como /getUsuarios2, erro 200 com "success: false" e listas sem paginação. Veja as convenções que tornam uma API REST fácil de usar e de manter.

Por Roger C. Ribeiro, fundador da Wecodex3 min de leitura

Rotas como /getUsuarios2, erro 200 com "success: false" e listas sem paginação. Veja as convenções que tornam uma API REST fácil de usar e de manter.

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

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

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: qual usar e quando.

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 Wecodex desenha e constrói APIs em Node.js para sistemas web e apps. Fale com a gente.

  • APIs
  • REST
  • Backend
  • Boas práticas
CompartilharWhatsAppLinkedIn

Escrito por

Roger C. Ribeiro

Fundador da Wecodex. Escreve sobre engenharia de software, performance, APIs, segurança e IA aplicada a empresas.

Serviços relacionados

Resolver de vez, com quem faz isso todo dia

Precisa de uma API ou integração que não caia quando o negócio crescer?

Este artigo mostra o caminho. A implementação sob medida, o detalhe que muda o resultado no seu caso, é o trabalho da Wecodex, empresa de engenharia do grupo Wocom.