REST API 设计 - 通过具有不同参数但相同 url 模式的 REST 获取资源

Question

我有一个与 REST URL 设计相关的问题。我在这里找到了一些相关的帖子Different RESTful representations of the same resource在这里 RESTful url to GET resource by different fields但对于最佳实践是什么以及原因，答复并不太清楚。这是一个例子。

我有用于表示“用户”资源的 REST URL。我可以获取具有 ID 或电子邮件地址的用户，但两者的 URL 表示形式保持相同。通过浏览大量博客和书籍，我发现人们一直在以多种不同的方式做到这一点。例如

在一本书和 stackoverflow 上的某个地方阅读这个实践(我似乎无法再次找到链接)

GET /users/id={id}
GET /users/email={email}

在很多博客上阅读这种做法

GET /users/{id}
GET /users/email/{email}

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

GET /users?id={id}
GET /users?email={email}

我的问题是，在所有这些实践中，哪一种对于使用 API 的开发人员最有意义？为什么？我相信在 REST URL 设计和命名约定方面没有一成不变的规则，但我只是想知道应该采取哪条路线来帮助开发人员更好地理解 API。

Answer 1

根据我的经验，GET/users/{id} GET/users/email/{email} 是最常见的方法。如果提供的 id 或 email 不存在，我还希望这些方法返回 404 Not Found。看到 GET/users/id/{id} 我也不会感到惊讶(尽管在我看来，这是多余的)。

对其他方法的评论

1. GET/users/id={id} GET/users/email={email}
   • 我认为我没有看到过这个，如果我看到了，那会很困惑。这几乎就像它试图用路径参数来模仿查询参数。
2. GET/users?id={id} GET/users?email={email}
   • 当您提到使用查询参数进行过滤时，我认为您击中了要害。
   • 使用 id 和 email 来调用此资源是否有意义(例如 GET/users?id ={id}&email={email})？如果没有，我就不会使用这样的单一资源方法。
   • 我希望此方法能够检索具有可选查询参数的用户列表以进行过滤，但我不希望使用 id、email或参数中的任何唯一标识符。例如:GET/users?status=BANNED 可能会返回被禁止的用户列表。

_{查看this answer来自相关问题。}