REST API DESIGN - Getting a resource through REST with different parameters but same url pattern
jax-rs, rest, url, url-pattern, url-scheme
Solution
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 an `email` (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.
Problem
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.