RESTful - Pílula 1 – URLs devem representar recursos e não ações

Um dos princípios fundamentais do REST é que sua API deve trabalhar com recursos, e não com ações.

Pense que cada recurso é uma entidade do domínio que sua aplicação gerencia — como users, posts, orders, products, etc.

Essas coleções representam conjuntos de instâncias. Por exemplo:

GET /users         → lista de usuários (coleção)
GET /users/10      → um usuário específico
GET /users/<uuid>  → um usuário específico com identificador global

Cada instância dentro da coleção (/users/10) é um recurso individual, identificado por um ID (numérico ou UUID).

---

Comportamento via métodos HTTP

Os verbos HTTP definem como você interage com os recursos:

Método	Descrição	Exemplo
GET	Lê recursos	GET /users ou GET /users/10
POST	Cria um novo recurso	POST /users
PUT / PATCH	Atualiza um recurso existente	PUT /users/10
DELETE	Remove um recurso	DELETE /users/10

Assim, o verbo expressa a ação, e a URL expressa o quê.

---

Evite ações na URL

❌ Errado:

POST /createUser
GET /getUserDetails?id=10

✅ Certo:

POST /users
GET /users/10

---

Resumo

• Use substantivos no plural para representar coleções
• Use métodos HTTP para representar ações
• Mantenha URLs limpas, consistentes e previsíveis