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

Solution 1: I recommend this:

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

---

Solution 2, another way:

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

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

---

我希望，这有帮助。

Answer 2

/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/该怎么办。

Answer 3

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

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

一般来说，总是要考虑为人类创建的HTML页面，通常也是应该为REST客户端创建的页面。

除非您只是想通过HTTP使用普通的JSON，否则就没有这样的约束。

Answer 4

首先为每个HTTP动词添加重要性。

• 使用GET，您可以列出并找到一个结果
• 使用POST插入
• PUT或PATCH进行更新
• 使用DELETE来删除某个键下的数据。

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

构建一个依赖此类合同的休息客户端相对简单。

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

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

这个article有更详细的信息和其他一些观点，看到这个opinionated article，选择HATEOAS。