api - REST API 如何对需要维护特定顺序的资源进行建模

Question

我们正在为我们的 API 设计一个新功能，我们偶然发现了一个进退两难的境地。

我们有两种不同类型的具有 1-N 关系的资源。
表示和层。
一个表示可以包含多个层。一个层只能属于一个表示。
我们遇到的问题是我们需要维护订单表示中的图层。

我们提出了两种方法:

第一种方法:链表

每一层都知道它的前一层。在数据库中，这是通过在包含另一个层的 id 的层表中拥有一个“父”字段来实现的。第一层将有一个“父”设置为 NULL。

然后通过以下 URI 通过 API 公开:

创建

GET /Representations/{repID}/layers

获取表示的所有层。可以通过遍历所有层并查看父字段来计算顺序。

POST /Representations/{repID}/layers

body :
标签:(字符串)
父级:LayerId

这用于通过在请求正文中指定父级来在特定位置创建和插入层。如果您将 Parent 设置为 NULL，则新创建的图层将是顺序中的第一个图层。
如果省略 Parent 字段，新创建的图层将位于订单的底部。
问题在于，在响应中，我们需要通知 api 使用者其他层由于新插入而改变了顺序。

更新

PUT /Representations/{repID}/layers/{layerId}

body :
标签:(字符串)
父级:LayerId
同样，您可以指定一个新的父级来重新排序图层，我们将再次需要发回有关已更改的所有其他图层的一些信息。

删除

DELETE /Representations/{repID}/layers/{layerId}

需要发回有关已更改的所有其他层的一些信息。

第二种方法: 图层 订单作为自己的资源

这个想法是层本身没有顺序的概念。它们只是一种资源。
然后你会得到一个 layerorder 资源，它负责保存有关图层顺序的信息。

因此，您仍将拥有图层的 CRUD 功能:
获取 - 发布 - 放置 - 删除

但是当您想了解有关他们订单的任何信息，或者您想更改他们的订单时，您将使用以下 uri:

/Representation/{repId}/layersorder

此资源将仅支持两种方法

GET /Representations/{repID}/layersorder

获取此表示中的图层 Id 的有序列表。

PUT /Representations/{repID}/layersorder

body :
[] - 新顺序中的层 Id 数组。
更新层的顺序。您需要以新顺序传递一个图层 id 数组作为请求的正文。 (例如 [1,3,2,4,6,5] )

按照第一种方法，无论何时添加或删除图层，您都需要通知 api 使用者另一个资源已更新。在第一种方法中是受更改影响的层列表，在这种方法中是层的新顺序(layersorder 资源)。

我想听听类似情况的意见和示例以及您如何解决问题。

谢谢。

Answer 1

我已经经历了你所描述的一部分。

在执行影响实体(或多个实体)的 PUT/POST 时，我喜欢在更改后返回完整对象。希望返回对象不是很大，但如果我使用你的 API，使用第一种方法......我会喜欢做一个 PUT/POST 并更新一个层，然后用更新的层信息取回完整的 Representation 对象。

它只是让我很容易确认我的更改，并立即开始使用新结构在我的代码中工作。我不喜欢执行 PUT/POST，然后必须执行额外的 GET 才能看到更改。

对于第二种方法......我需要做的工作越多来调用 API，我就越沮丧。我不确定我是否读对了，但是要使用第二种方法进行 PUT，似乎我必须构建整个表示和图层对象来更新一条数据。那会令人沮丧。

我更喜欢第一种方法的语法，但使用第二种方法的概念。换句话说，这是我希望在 PUT/POST/GET 之后看到的文档:

{
"type" : "Representation",
"id" : 1,
"layers" : [
{ "id" : 1, "name" : "the first layer", "order" : 1, "parent" : "" },
{ "id" : 2, "name" : "the second layer", "order" : 2, "parent" : 1 },
{ "id" : 3, "name" : "the third layer", "order" : 3, "parent" : 1 }
]
}

它已经为我排序，所以我不必做这项工作，但也有用于生成排序的信息以防万一。我已经用 REST API 做到了这一点，它似乎对用户很有用。