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).
Comments on the other approaches
GET /users/id={id} GET /users/email={email}
- I don’t think I’ve seen this, and if I did see it, it would be very confusing. It’s almost like it’s trying to imitate query parameters with path parameters.
GET /users?id={id} GET /users?email={email}
- I think you hit the nail on the head when you mentioned using query parameters for filtering.
- Would it ever make sense to call this resource with both an
id
and anemail
(e.g.GET /users?id={id}&email={email}
)? If not, I wouldn’t use a single resource method like this. - I would expect this method for retrieving a list of users with optional query parameters for filtering, but I would not expect
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.