恢复设计的端点,以过滤并仅返回最新创建的资源



我有一个应用程序,用户可以为给定的一个子资源创建许多子资源。假设端点看起来像这样:

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

子资源包含一段时间的时间限制了日期作为身体的一部分,类似于:

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

它们也是考虑价值对象。就应用程序而言,它们没有ID(即使它们是由SQL数据库备份的,即使它们有效地备份了),因为在不经过主要的搜索子资源的情况下搜索子资源没有任何意义。

现在,我想创建一个端点,允许用户找到给定主要资源的子资源,但它必须仅返回最新创建的时期,该时间段包含给定的日期。如下:

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

我的问题是latest对我来说似乎是一个过滤器。latest每次调用时都可以返回不同的值,具体取决于用户是否创建了新的子资源,通过我的理解并不静止。我认为它应该更像:

,而不是以前的端点。
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

在我的用例中,它提供了更多选择,但实际上不需要。

这样做,用户通常会期望一个结果,但这会关闭其他类型的过滤门,例如在日期之前过滤。

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

还有其他选择吗?

我的问题是latest对我来说似乎是一个过滤器。latest每次调用时都可以返回不同的值,具体取决于用户是否创建了新的子资源,通过我的理解,这并不静止。

latest标识符似乎很好。请参阅菲尔丁论文第5章中的以下报价,其中定义了其余的体系结构样式:

某些资源是静态的,从某种意义上说,当创建后的任何时间检查时,它们始终与相同的值设置相对应。其他人随着时间的推移价值有很大的差异。对于资源而言,唯一需要静态的是映射的语义,因为语义是将一种资源与另一个资源区分开来的。

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

最新更新