端点的 RESTful 设计以过滤并仅返回最新创建的资源 [英] RESTful design for an endpoint to filter and return only the latest created resource

问题描述

我有一个应用程序，用户可以在其中为给定的资源创建许多子资源.假设端点如下所示:

I have an application where a user can create many subresources for a given one. Let's say the endpoint looks like this:

POST /main-resources/{id}/sub-resources

子资源包含一段受日期限制的时间段作为正文的一部分，例如:

The subresource contains a period of time limited by dates as part of the body, something like:

{
    "startDate": "2018-10-10",
    "endDate": "2018-12-12"
}

它们也被认为是值对象.就应用程序而言，它们没有 id(即使它们由 SQL 数据库备份，因此它们有一个如此有效)，因为在这种情况下搜索子资源而不通过主资源是没有意义的.

They are also consider value objects. In terms of the application, they don't have an id (even though they are backup by a SQL database so effectively they have one) as it doesn't make sense to search for a subresource without going through the main one in this case.

现在，我想创建一个端点，允许用户查找给定主资源的子资源，但它必须只返回创建的最新一个，该时间段包含给定日期.类似于以下内容:

Now, I would like to create an endpoint that allows the user to find the subresources for a given main resource but it has to return just the latest one created which period of time contains a given date. Something like the following:

GET /main-resources/{id}/sub-resources/latest?date=2018-11-11

我的问题是 latest 对我来说似乎是一个过滤器.latest 每次被调用时都可以返回不同的值，这取决于用户是否创建了新的子资源，据我所知，它不是 RESTful.而不是之前的端点，我认为它应该看起来更像:

My problem here is that latest seems like a filter to me. latest can return different values each time it is called depending on whether the user has created new subresources which by my understanding it's not RESTful. Instead of the previous endpoint, I think it should look more like:

GET /main-resources/{id}/sub-resources?latest=true&date=2018-11-11

或

GET /main-resources/{id}/sub-resources?limit=1&date=2018-11-11&order=desc

它提供了更多选项，但在我的用例中实际上并不需要.

which gives more options but won't actually be needed in my use case.

这样做，用户通常会期望一个结果，但这会为其他类型的过滤(例如仅按日期过滤)关闭大门.

Doing it this way, the user would normally expect one result but that would close the door to other types of filtering like filtering just by the date.

所以基本上我可以选择创建一个包含 latest 作为路径变量的端点，它将返回单个元素，或者将其用作通常必须返回一个列表的参数即使此过滤器指定用户只想要一个元素，也会让客户端更加烦人.

So basically I have the option to create an endpoint that includes latest as a path variable, which would return a single element, or use it as a parameter which would normally have to return a list of elements even though this filter specifies the user only wants one, making it a little bit more annoying for the client.

还有其他选择吗?

推荐答案

我的问题是 latest 对我来说似乎是一个过滤器.latest 每次调用时都可以返回不同的值，具体取决于用户是否创建了新的子资源，据我所知，这不是 RESTful.

My problem here is that latest seems like a filter to me. latest can return different values each time it is called depending on whether the user has created new subresources which by my understanding it's not RESTful.

latest 标识符似乎没问题.请参阅 Fielding 论文的 第 5 章中的以下引述，其中定义了 REST 架构风格:

The latest identifier seems to be just fine. See the following quote from the chapter 5 of Fielding's dissertation, where the REST architectural style is defined:

某些资源在某种意义上是静态的，即在创建后的任何时间进行检查时，它们始终对应于相同的值集.其他人的价值随着时间的推移有很大程度的变化.资源唯一需要静态的是映射的语义，因为语义是区分一种资源与另一种资源的原因.

Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time. The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another.

例如，学术论文的作者首选版本"是一个其值随时间变化的映射，而到在会议 X 会议记录中发表的论文"的映射是静态的.这是两种不同的资源，即使它们在某个时间点都映射到相同的值.区分是必要的，以便可以独立识别和引用这两种资源.软件工程中的一个类似示例是在提及最新修订版"、修订版号 1.2.7"或橙色版本中包含的修订版"时，单独标识受版本控制的源代码文件.

For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently. A similar example from software engineering is the separate identification of a version-controlled source code file when referring to the "latest revision", "revision number 1.2.7", or "revision included with the Orange release."

这篇关于端点的 RESTful 设计以过滤并仅返回最新创建的资源的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！