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

折月煮酒 提交于 2019-11-27 17:04:44
DannyMo

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.

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

About the user resources

on the path /users you will always get a collection resource returned.

on the path /users/[user_id] you will get a singleton resource representing the user with its id [user_id] or alternatively a 404 response if no user exists with the requested [user_id] (or forbidden (401) if you are not allowed to access the requested user resource, etc). Each resource path has only one single identifier and you use this to find/identify the resources. It is not possible to use several identifiers for the same resource on the same resource path. If you get a resource returned in a response that identifier is included in the response as a self HREF to locate/identify the resource.

You can query the path /users with GET/query parameters. This will return a collection with users that meet the requested criteria. The collection that is returned contains the user resources, all with their identifying self HREF.

About the email resources

If I look at what you suggested for email I would rather think the following:

Emails from users are also resources. So I would think that /users/[user_id]/emails returns a collection of email addresses for user with id user_id. /users/[user_id]/emails/[email_id] returns the email of user with user_id and ['email_id']. What you use as an identifier is up to you, but I would stick to an integer. You can delete an email from the user by sending a DELETE request to the path that identifies the email you want to delete. So for example DELETE on /users/[user_id]/emails/[email_id] will delete the email with email_id that is owned by user with user_id. Most likely only that user is allowed to perform this delete operation. Other users will get a 401 response.

If a user can have only one email address you can stick to /users/[user_id]/email This returns a singleton resource. The user can update his email address by PUTting or POSTing a new email address at that url. If in your application you do not allow users without an email you should respond with a 401 if he sends a DELETE request to that url.

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!