REST API 何时使用查询参数或请求参数？答案

【问题标题】：REST API When to use query params or request params?REST API 何时使用查询参数或请求参数？
【发布时间】：2019-01-27 00:12:45
【问题描述】：

我有一个包含workout-plans 的表的数据库。数据示例如下：

{
  id: 1,
  level: 'beginner'
  week_index: 1
},
{
  id: 2,
  level: 'beginner'
  week_index: 2
},
{
  id: 3,
  level: 'advanced'
  week_index: 1
}

使用week_index 和level 获取特定项目的最佳方法是什么。这些是我目前的想法，但我不知道 REST API 的最佳实践。

/workout-plans?level=beginner&week=1
/workout-plans/beginner/1
/workout-plans/beginner?week=1

【问题讨论】：

【解决方案1】：

/workout-plans/ 是锻炼计划列表的路径。所以它总是返回一个列表，即使只有 1 个结果。

所以/workout-plans/?level=beginner&week=1 产生 1 个结果，但作为一个列表。

如果这是解决其中一个问题的理想方式（按级别和周，而不是按 id），那么获取其中一个的 URL 将类似于

/workout-plans/1/beginner/
/workout-plans/beginner/1/
/workout-plans/beginner-1/

或者类似的东西。

我更喜欢最后一个，因为它不建议在完整列表和详细路径之间存在级别；如果你选择第一个，那么如果有人问/workout-plans/1/怎么办。

【讨论】：

我会说 /workout-plans/1 将是 /workout-plans/:id - 它会得到行的 ID。所以这就是我想避免混淆的地方！查询参数似乎更好?

【解决方案2】：

我认为，您应该使用/workout-plans?level=beginner&week=1。因为，通过这种方式，很明显你是在向workout-plans控制器请求数据。

或者，您可以使用：/workout-plans/level/beginner/week/1

如：Rails中，路由配置可以这样：
/workout-plans/level/:level/week/:week

希望对你有帮助。

【讨论】：

【解决方案3】：

获取特定项目的 RESTful 方式是创建一个表单。你知道，就像网络上的表格一样。在这个“搜索表单”中，客户将输入周和级别，并会得到结果或重定向到适用的锻炼列表。

结果页面的确切 URI 无关紧要，尽管您的第一个带有路径参数的解决方案与纯 HTML 表单兼容，因此可以使用 HTML GET 表单开箱即用，这很好。

一般来说，始终考虑您将为人类创建哪些 HTML 页面，通常也应该为 REST 客户端创建这些页面。

除非您只想要通过 HTTP 的纯 JSON，在这种情况下没有这样的限制。

【讨论】：

【解决方案4】：

首先为每个 HTTP 动词添加意义。

避免使用路径参数作为过滤器，更喜欢使用查询参数来做到这一点。

构建一个REST客户端来依赖这样的合约相对简单。

此外，欢迎使用具有适当默认值的 page 和 pageSize 等特殊查询参数。

由于您正在设计 API，请尝试返回有意义的状态代码和消息。

此article 有更详细的信息，对于其他一些观点，请参阅此opinionated article，选择 HATEOAS。

【讨论】：