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

问题描述

我有一个与 REST url 设计相关的问题.我在这里找到了一些相关的帖子:同一资源的不同 RESTful 表示在这里:通过不同字段获取资源的 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}

Query params 通常用于过滤 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 url 设计和命名约定方面没有一成不变的规则，但我只是想知道我应该走哪条路来帮助开发人员更好地理解 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 设计 - 通过 REST 获取具有不同参数但具有相同 url 模式的资源的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！