api - 过滤条件的查询字符串与资源路径

Question

背景

我有 2 个资源:courses 和 professors。

类(class)具有以下属性:

• 编号
• 主题
• semester_id
• 年
• 部分
• 教授编号

教授具有以下属性:

• 编号
• 教师
• super 用户
• 名字
• 姓氏

因此，您可以说一门类(class)有一位教授，而一位教授可能有很多门类(class)。

如果我想获得所有类(class)或所有教授，我可以:GET/api/courses 或 GET/api/professors 分别。

---

困境

当我想获得某位教授教授的所有类(class)时，我的困境就来了。

我可以使用以下任一方法:

• GET/api/professors/:prof_id/courses
• GET/api/courses?professor_id=:prof_id

不过我不确定该用哪个。

---

当前解决方案

目前，我正在使用后者的增强形式。我的理由是，如果我想添加过滤/排序标准，它的可扩展性会更高。

我实际上是在将 JSON 字符串编码/嵌入到查询参数中。因此，一个(解码的)示例可能是:

GET /api/courses?where={professor_id: "teacher45", year: 2016}&order={attr: "topic", sort: "asc"}

上面的请求将检索在 2016 年由提供的 professor_id 教授教授的所有类(class)(或当前正在教授)，并根据主题标题以 ASCII 升序排序。

虽然我从来没有见过有人这样做，所以我想知道我是否在做一些愚蠢的事情。

---

结束问题

是否有使用查询字符串与资源路径作为过滤条件的标准做法？过去一些较大的 API 做了什么？是否可以接受或鼓励同时使用这两种范例(使两个端点都可用)？如果我确实应该使用第二种范式，除了编码 JSON 之外，还有更好的组织方法我可以使用吗？有人见过另一个在查询字符串中使用 JSON 的公共(public) API 吗？

---

经过编辑以减少基于意见的内容。 (见评论)

Answer 1

正如在之前的评论中所解释的那样，REST 不太关心标识唯一资源的链接的实际形式，除非 RESTful constraints或违反超文本传输​​协议(protocol) (HTTP) 本身。

关于使用查询或路径(甚至矩阵)参数完全取决于您。有 no fixed rule什么时候用什么只是个人喜好。

我喜欢使用查询参数，尤其是当值是可选的并且不需要像 JAX-RS 这样的大量框架时，即允许定义默认值。查询参数通常被认为可以避免缓存响应，然而 is more an urban legend then the truth ，尽管某些实现可能仍会忽略对包含查询字符串的 URI 进行缓存的响应。

如果参数定义了某种特定的 flavor 属性(即汽车颜色)，我更愿意将它们放入矩阵参数中。它们也可以出现在 URI 的中间，即 /api/professors;hair=grey/courses 可以返回头发颜色为灰色的教授持有的所有类(class)。

在我的理解中，路径参数是应用程序完成请求所需的强制参数，否则将不会首先在服务端调用相应的方法处理程序。通常这是一些资源标识符，例如分配给特定实体的表行 ID 或 UUID。

关于描述关系，我通常从 1:n 关系的 1 部分开始。如果我面对一个 m:n 关系，就像你与教授的情况一样 - 类(class)，我通常会更容易地从可能存在的实体开始。教授仍然是教授，即使他没有举办任何讲座(在特定期限内)。如果没有可用的教授，类(class)就不会成为类(class)，我会把教授放在类(class)之前，尽管关于 REST 类(class)仍然是很好的顶级资源。

因此我会更改您的查询

GET /api/courses?where={professor_id: "teacher45", year: 2016}&order={attr: "topic", sort: "asc"}

类似于:

GET /api/professors/teacher45/courses;year=2016?sort=asc&onField=topic

我稍微更改了您的字段的语义，因为年份属性可能更适合类(class)而不是教授资源，因为教授已经通过教授 ID 减少为单一资源。但是，这些类(class)应仅限于仅包括 2016 年举办的类(class)。由于排序是可选的，并且可能指定了默认值，因此我非常适合将其放入查询参数部分。排序的字段与排序本身有关，因此也属于查询参数。我将年份放入矩阵参数中，因为这是类(class)本身的特定属性，例如汽车的颜色或汽车的制造年份。

但如前所述，这是相当自以为是的，可能与您或其他人的观点不符。