I have a question related to REST url design. I found some relevant posts here: Different RESTful representations of the same resource and here: RESTful url to GET resource by different fields but the responses are not quite clear on what the best practices are and why. Here's an example.
I have REST urls for representing "users" resource. I can GET a user with an id or with an email address but the URL representation remains the same for both. Going through a lot of blogs and books I see that people have been doing this in many different ways. For example
read this practice in a book and somewhere on stackoverflow (I can't seem to find the link again)
GET /users/id={id}
GET /users/email={email}
read this practice on a lot of blogs
GET /users/{id}
GET /users/email/{email}
Query params are normally used for filtering the results of the resources represented by the url, but I have seen this practice being used as well
GET /users?id={id}
GET /users?email={email}
My question is, out of all these practices, which one would make the most sense to developers consuming the apis and why? I believe there are no rules set in stone when it comes to REST url designs and naming conventions, but I just wanted to know which route I should take to help developers better understand the apis.
All help appreciated !
In my experience, GET /users/{id} GET /users/email/{email}
is the most common approach. I would also expect the methods to return a 404 Not Found if a user doesn't exist with the provided id
or email
. I wouldn't be surprised to see GET /users/id/{id}
, either (though in my opinion, it is redundant).
GET /users/id={id} GET /users/email={email}
GET /users?id={id} GET /users?email={email}
id
and an email
(e.g. GET /users?id={id}&email={email}
)? If not, I wouldn't use a single resource method like this.id
, email
or any unique identifier to be among the parameters. For example: GET /users?status=BANNED
might return a list of banned users.Check out this answer from a related question.