用于过滤条件的查询字符串与资源路径 [英] Query String vs Resource Path for Filtering Criteria

问题描述

我有 2 个资源:courses 和 professors.

I have 2 resources: courses and professors.

course 具有以下属性:

• id
• 主题
• semester_id
• 年
• 部分
• 教授_id

professor 具有以下属性:

• id
• 教师
• 超级用户
• 名字
• 姓氏

所以，你可以说一门课程有一个教授，而一个教授可能有很多门课程.

So, you can say that a course has one professor and a professor may have many courses.

如果我想获取所有课程或所有教授，我可以分别:GET/api/courses 或 GET/api/professors.

If I want to get all courses or all professors I can: GET /api/courses or GET /api/professors respectively.

当我想获得某位教授教授的所有课程时，我的窘境就来了.

My quandary comes when I want to get all courses that a certain professor teaches.

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

I could use either of the following:

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

不过我不确定要使用哪个.

I'm not sure which to use though.

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

Currently, I'm using an augmented form of the latter. My reasoning is that it is more scale-able if I want to add in filtering/sorting criteria.

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

I'm actually encoding/embedding JSON strings into the query parameters. So, a (decoded) example might be:

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

上述请求将检索教授在 2016 年使用所提供的professional_id 教授(或正在教授)的所有课程，按照主题标题以 ASCII 升序排序.

The request above would retrieve all courses that were (or are currently being) taught by the professor with the provided professor_id in the year 2016, sorted according to topic title in ascending ASCII order.

不过，我从未见过有人这样做过，所以我想知道我是否在做一些愚蠢的事情.

I've never seen anyone do it this way though, so I wonder if I'm doing something stupid.

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

Is there a standard practice for using the query string vs the resource path for filtering criteria? What have some larger API's done in the past? Is it acceptable, or encouraged to use use both paradigms at the same time (make both endpoints available)? If I should indeed be using the second paradigm, is there a better organization method I could use besides encoding JSON? Has anyone seen another public API using JSON in their query strings?

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

Edited to be less opinion based. (See comments)

推荐答案

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

As already explained in a previous comment, REST doesn't care much about the actual form of the link that identifies a unique resource unless either the RESTful constraints or the hypertext transfer protocol (HTTP) itself is violated.

关于查询或路径(甚至矩阵)参数的使用完全取决于您.没有固定规则何时使用什么，而只是个人偏好.

Regarding the use of query or path (or even matrix) parameters is completely up to you. There is no fixed rule when to use what but just individual preferences.

我喜欢使用查询参数，特别是当该值是可选的并且不需要像 JAX-RS 这样的大量框架时，即允许定义默认值.查询参数通常被认为是为了避免缓存响应，然而 更像是一个都市传说事实，尽管某些实现可能仍会忽略缓存包含查询字符串的 URI 的响应.

I like to use query parameters especially when the value is optional and not required as plenty of frameworks like JAX-RS i.e. allow to define default values therefore. Query parameters are often said to avoid caching of responses which however is more an urban legend then the truth, though certain implementations might still omit responses from being cached for an URI containing query strings.

如果参数定义了诸如特定风味属性(即汽车颜色)之类的东西，我更喜欢将它们放入矩阵参数中.它们也可以出现在 URI 的中间，即 /api/professors;hair=grey/courses 可以返回由头发颜色为灰色的教授持有的所有课程.

If the parameter defines something like a specific flavor property (i.e. car color) I prefer to put them into a matrix parameter. They can also appear within the middle of the URI i.e. /api/professors;hair=grey/courses could return all cources which are held by professors whose hair color is grey.

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

Path parameters are compulsory arguments that the application requires to fulfill the request in my sense of understanding otherwise the respective method handler will not be invoked on the service side in first place. Usually this are some resource identifiers like table-row IDs ore UUIDs assigned to a specific entity.

关于描绘关系，我通常从 1:n 关系的 1 部分开始.如果我面临 m:n 关系，就像你与教授的情况一样 - 课程，我通常从可能更容易存在的实体开始.教授仍然是教授，即使他不举办任何讲座(在特定期限内).如果没有教授可用，一门课程就不会是一门课程，我会将教授放在课程之前，尽管就 REST 课程而言，它仍然是很好的顶级资源.

In regards to depicting relationships I usually start with the 1 part of a 1:n relationship. If I face a m:n relationship, like in your case with professors - cources, I usually start with the entity that may exist without the other more easily. A professor is still a professor even though he does not hold any lectures (in a specific term). As a course wont be a course if no professor is available I'd put professors before cources, though in regards to REST cources are fine top-level resources nonetheless.

因此我会更改您的查询

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

我稍微改变了你的领域的语义，因为 year 属性可能更适合课程而不是教授资源，因为教授已经通过教授 id 减少到单个资源.然而，这些课程应该仅限于包括 2016 年举办的课程.由于排序是可选的，并且可能指定了默认值，因此这是我放入查询参数部分的完美候选.要排序的字段与排序本身有关，因此也属于查询参数.我已将年份放入矩阵参数中，因为这是课程本身的特定属性，例如汽车的颜色或汽车的制造年份.

I changed the semantics of your fields slightly as the year property is probably better suited on the courses rather then the professors resource as the professor is already reduced to a single resource via the professors id. The courses however should be limited to only include those that where held in 2016. As the sorting is rather optional and may have a default value specified, this is a perfect candidate for me to put into the query parameter section. The field to sort on is related to the sorting itself and therefore also belongs to the query parameters. I've put the year into a matrix parameter as this is a certain property of the course itself, like the color of a car or the year the car was manufactured.

但正如之前已经解释过的，这是相当固执的观点，可能与您或其他人的观点不符.

But as already explained previously, this is rather opinionated and may not match with your or an other folks perspective.

这篇关于用于过滤条件的查询字符串与资源路径的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！