DEV Community

Cover image for RESTful - Pílula 2 – Estrutura e hierarquia de URLs
Anderson Contreira
Anderson Contreira

Posted on

RESTful - Pílula 2 – Estrutura e hierarquia de URLs

#braziliandevs #development #rest #code

Uma API RESTful bem projetada deve ter URLs organizadas e previsíveis, que representem a relação entre recursos.
A estrutura das rotas comunica a hierarquia e o contexto de cada entidade dentro do domínio da aplicação.

Representando coleções e instâncias

Como vimos na pílula anterior, recursos são representados por coleções e instâncias.

GET /users         → coleção de usuários  
GET /users/10      → um usuário específico
Enter fullscreen mode Exit fullscreen mode

Essa convenção pode ser aplicada a qualquer entidade do sistema (posts, orders, companies, products etc.).

Hierarquia entre recursos

Quando um recurso depende de outro, por exemplo, pedidos de um usuário, podemos representar essa relação de forma hierárquica:

GET /users/10/orders           → lista de pedidos do usuário 10  
GET /users/10/orders/99        → pedido 99 do usuário 10
Enter fullscreen mode Exit fullscreen mode

Isso mostra claramente o contexto do recurso: o pedido pertence ao usuário.

Outra dica importante de segurança é:

Procure usar UUIDs em vez de IDs diretamente nas URLs; isso previne ações de pessoas mal-intencionadas.

GET /users/<uuid>/orders           → lista de pedidos do usuário  
GET /users/<uuid>/orders/<uuid>        → pedido X do usuário Y
Enter fullscreen mode Exit fullscreen mode

Quando (e quando não) usar hierarquia

✅ Use hierarquia quando o sub-recurso não faz sentido existir fora do contexto do pai.
Exemplo:

  • /users/10/orders → o pedido pertence a um usuário específico.

❌ Evite hierarquias profundas, como:

/companies/1/departments/2/employees/3/projects/4/tasks/5
Enter fullscreen mode Exit fullscreen mode

Isso dificulta manutenção e compreensão. Nesse caso, prefira algo mais direto:

/tasks/5
Enter fullscreen mode Exit fullscreen mode

E, se necessário, use filtros ou relacionamentos na query string:

/tasks?userId=3
Enter fullscreen mode Exit fullscreen mode

URLs limpas e consistentes

Boas práticas de formatação:

Regra Exemplo
Use letras minúsculas /users, não /Users
Separe palavras com hífen (-) /user-profiles, não /user_profiles
Evite sufixos técnicos /users, não /users.json
Evite barras no final /users, não /users/

Resumo

  • Use coleções para grupos e instâncias para itens específicos
  • Represente relações com hierarquias simples e intuitivas
  • Evite profundidade excessiva nas URLs
  • Mantenha consistência e legibilidade

Top comments (0)