REST API设计-通过具有不同参数但URL模式相同的REST获取资源 [英] REST API DESIGN - Getting a resource through REST with different parameters but same url pattern

问题描述

我有一个与REST网址设计有关的问题.我在这里找到了一些相关的帖子:同一资源的不同RESTful表示形式此处:通过不同字段获取GET资源的RESTful URL ，但是关于什么是最佳做法以及原因，答案并不十分清楚.这是一个例子.

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.

我有代表用户"资源的REST网址.我可以使用ID或电子邮件地址来获取用户，但两者的URL表示形式均相同.在浏览许多博客和书籍时，我看到人们一直在以许多不同的方式来做这件事.例如

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

在一本书中以及stackoverflow上的某处阅读这种做法(我似乎再也找不到链接了)

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}

查询参数通常用于过滤由url表示的资源的结果，但是我也看到了这种做法

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}

我的问题是，在所有这些实践中，哪种方法最适合使用api的开发人员，为什么?我相信在REST网址设计和命名约定方面没有定律，但是我只是想知道我应该采取哪种途径来帮助开发人员更好地理解api.

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.

感谢所有帮助！

推荐答案

以我的经验，GET /users/{id} GET /users/email/{email}是最常见的方法.我还希望如果提供的id或email不存在用户，则该方法将返回404 Not Found.我也不会对GET /users/id/{id}感到惊讶(尽管我认为这是多余的).

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).

1. GET /users/id={id} GET /users/email={email}
   • 我认为我没有看过，如果我看过，那将非常令人困惑.几乎就像它试图模仿带有路径参数的查询参数一样.

• 当您提到使用查询参数进行过滤时，我认为您很满意.
• 用两者以及id和email(例如GET /users?id={id}&email={email})来调用此资源是否有意义?如果没有，我不会使用像这样的单一资源方法.
• 我希望此方法可检索带有可选查询参数的用户列表进行过滤，但是我不希望参数中包含id，email或任何唯一标识符.例如:GET /users?status=BANNED可能返回禁止用户的列表.

• 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.

_{从一个相关问题中查看此答案.}

这篇关于REST API设计-通过具有不同参数但URL模式相同的REST获取资源的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！