Não gosto de ver a {id}
parte dos URLs se sobrepor aos sub-recursos, pois, id
teoricamente, isso poderia ser qualquer coisa e haveria ambiguidade. Está misturando diferentes conceitos (identificadores e nomes de sub-recursos).
Problemas semelhantes são freqüentemente vistas em enum
constantes ou pasta estruturas, onde diferentes conceitos são misturados (por exemplo, quando você tem pastas Tigers
, Lions
e Cheetahs
, em seguida, também uma pasta chamada Animals
no mesmo nível - isso não faz sentido como um é um subconjunto do de outros).
Em geral, acho que a última parte nomeada de um endpoint deve ser singular se lida com uma única entidade de cada vez e plural se lida com uma lista de entidades.
Portanto, terminais que lidam com um único usuário:
GET /user -> Not allowed, 400
GET /user/{id} -> Returns user with given id
POST /user -> Creates a new user
PUT /user/{id} -> Updates user with given id
DELETE /user/{id} -> Deletes user with given id
Depois, há um recurso separado para fazer consultas aos usuários, que geralmente retornam uma lista:
GET /users -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x -> Gets top X active users
E aqui estão alguns exemplos de um sub-recurso que lida com um usuário específico:
GET /user/{id}/friends -> Returns a list of friends of given user
Faça um amigo (link muitos para muitos):
PUT /user/{id}/friend/{id} -> Befriends two users
DELETE /user/{id}/friend/{id} -> Unfriends two users
GET /user/{id}/friend/{id} -> Gets status of friendship between two users
Nunca há ambiguidade, e a nomeação plural ou singular do recurso é uma dica para o usuário o que ele pode esperar (lista ou objeto). Não há restrições sobre id
s, teoricamente tornando possível ter um usuário com o ID new
sem sobrepor-se a um nome de sub-recurso (potencial futuro).