No artigo de hoje, vamos falar sobre uma prática da qual eu já fui vítima, e você, leitor, provavelmente também já foi (ou ainda está sendo).
Trata-se da famigerada prática de criar endpoints excessivamente verbosos. Quando estamos desenvolvendo uma API REST para nosso sistema, é comum tentarmos facilitar o acesso a dados muito específicos. No entanto, isso muitas vezes se transforma em uma bola de neve.
Quem nunca se pegou pensando: “Só mais um endpoint e tudo estará resolvido”... e repetiu isso incontáveis vezes?
Isso acontece porque ignoramos um fator muito importante no conceito de API: ela deve servir como um portal de acesso aos recursos gerais do sistema, e não como um grande servidor repleto de rotas altamente específicas para cada situação.
Esse problema costuma surgir, principalmente, quando lidamos com recursos que estão relacionados entre si.
Pense na seguinte situação:
Você precisa listar usuários que possuem tarefas atribuídas. A abordagem comum e tentadora é criar um endpoint como:
/getUsersWithTasks
Mas esse tipo de design fere princípios fundamentais de uma API bem construída. Em vez disso, pense na sua API como uma interface para recursos, e usuários são um recurso. Logo, uma forma mais adequada e escalável seria algo como:
/users?withTasks=true
Esse formato segue o padrão REST, é mais flexível e permite expandir facilmente os filtros no futuro, como:
/users?withTasks=true&active=true
Dicas gerais
Evite criar endpoints com verbos como get, delete ou create. Além de quebrar os princípios REST, isso torna sua API redundante e desnecessariamente verbosa. Por exemplo:
🚫 /getUserById
✅ /users/:id
Além disso:
Prefira filtros via query parameters em vez de encher a URL com parâmetros.
Mantenha seus endpoints focados em recursos, não em ações.
Seguindo essas dicas simples, sua API se tornará muito mais limpa, intuitiva, escalável e fácil de manter.
Top comments (0)