resturljax-rsurl-schemeurl-pattern

REST API DESIGN - Getting a resource through REST with different parameters but same url pattern

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.

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

    1. 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.
    2. 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.