Design de Rotas: Por que Substantivos são o "Golden Standard" em APIs RESTful?

Introdução

No desenvolvimento de APIs modernas, a clareza da interface é tão importante quanto a eficiência do código. Para desenvolvedores que buscam o nível Senior, compreender a semântica do protocolo HTTP é o primeiro passo para criar sistemas resilientes. Um dos erros mais comuns em projetos iniciantes é a confusão entre recursos e ações na construção das URLs.

Neste artigo, vamos explorar por que o uso de substantivos em vez de verbos é a prática recomendada para arquiteturas RESTful e como isso transforma a experiência de quem consome sua API.

1. O Recurso como Protagonista

No modelo REST (Representational State Transfer), o foco está no Recurso. Um recurso é qualquer entidade de dados que sua API expõe: um usuário, uma transação financeira ou um sinal de mercado.

A URL deve servir como o identificador único desse recurso (URI). Quando usamos substantivos, estamos nomeando a entidade.

• Certo: GET /v1/ativos (Identifica a coleção de ativos)
• Errado: GET /v1/buscarAtivos (Mistura ação com identificação)

2. A Semântica dos Verbos HTTP

A beleza do REST reside na separação de responsabilidades. O substantivo na URL diz o que você está manipulando, enquanto o Verbo HTTP diz como você está manipulando.

VerboSubstantivo (Rota)Ação ResultanteGET/pedidosRecupera a lista de pedidosPOST/pedidosCria um novo pedidoPUT/pedidos/123Atualiza o pedido 123DELETE/pedidos/123Remove o pedido 123

Perceba que a rota /pedidos permanece constante. O que muda é a intenção da operação através do método HTTP. Isso torna a API previsível e consistente.

3. Vantagens da Padronização

Legibilidade e Intuição

Uma API que utiliza substantivos é "autodocumentada". Se eu sei que existe um recurso chamado /usuarios, eu automaticamente deduzo que um POST ali servirá para cadastro, sem precisar ler páginas de documentação.

Consistência Técnica

Ao evitar verbos como /getUsuarios ou /deleteUsuarios, eliminamos a redundância. O protocolo HTTP já possui o método DELETE; usar o verbo na URL é como dizer "subir para cima".

Evolução e Versatilidade

Substantivos permitem que a API cresça de forma hierárquica e organizada:

• /usuarios/45/enderecos (Recupera endereços de um usuário específico)

4. Dica de Elite: Plural ou Singular?

Embora não exista uma regra técnica rígida, o consenso da comunidade e das grandes empresas de tecnologia (como Google e Microsoft) é o uso do plural.

• Use /contas em vez de /conta.

Isso ajuda a manter a consistência visual quando você precisa acessar um item específico dentro de uma coleção: /contas/001.