Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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.

All help appreciated !

like image 504
shahshi15 Avatar asked Dec 04 '13 17:12

shahshi15


People also ask

How do I pass multiple query parameters in REST URL?

Query parameters are passed after the URL string by appending a question mark followed by the parameter name , then equal to (“=”) sign and then the parameter value. Multiple parameters are separated by “&” symbol.

Can the same URL belong to several resources?

A URI can point to at most one resource, but many URIs can point to the same resource. A many-to-one relationship between URIs and resources, if you will.

Which URL pattern is recommended when working with one resources and a collection of resources?

URL Structure The recommended convention for URLs is to use alternate collection / resource path segments, relative to the API entry point.

Is it possible to have multiple representations for the same resource in REST?

You could make them 2 representations of the same resource and with content negotiation.. 100% restful.


2 Answers

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.

like image 61
DannyMo Avatar answered Sep 20 '22 13:09

DannyMo


Looking at this pragmatically, you've got a collection of users:

/users   # this returns many 

Each user has a dedicated resource location:

/users/{id}    # this returns one 

You've also got a number of ways to search for users:

/users?email={email} /users?name=*bob* 

Since these are all query parameters to /users, they should all return lists.. even if it's a list of 1.

I wrote a blog post on pragmatic RESTful API design here that talks about this, among other things, here: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

like image 32
Vinay Sahni Avatar answered Sep 19 '22 13:09

Vinay Sahni