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

Question

我有一个数据库，该数据库的表包含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

Answer 1

/workout-plans/是锻炼计划的 list 的路径。因此，即使只有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/，该怎么办。

Answer 2

解决方案1：我建议这样做：

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

---

解决方案2，另一种方式：

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

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

---

我希望这会有所帮助。

Answer 3

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

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

通常，请始终考虑要为人类创建哪些HTML页面，通常也应该为REST客户端创建这些HTML页面。

除非您只希望通过HTTP使用纯JSON，否则在这种情况下就没有此类约束。

Answer 4

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

• 使用 GET ，您可以列出并找到一个结果
• 使用 POST 插入
• PUT 或 PATCH 获取更新
• 使用 Delete 删除特定密钥下的数据。

避免将路径参数用作过滤器，而建议使用查询参数。

建立一个休息客户来依靠这种合同相对简单。

此外，还欢迎使用特殊查询参数（例如具有正确的默认值的page和pageSize）。

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

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