集合上的 Restful PATCH 用于批量更新排序参数

Question

我们有一个包含许多实体(“项目”)的大列表(“集合”)。这一切都是通过 RESTful 接口(interface)进行管理的。可以通过项目上的 order 属性对项目进行手动排序。查询时，数据库会根据顺序列出集合中的所有项目。

现在我们希望向用户公开这一机制，他们可以在一次调用中更新所有项目的完整排序。数据库不允许相同 collection_id 具有相同的 order(唯一的 collection_id + order)，因此您可以不会(也绝对不应该)一一更新所有项目。

我想到了 PATCH 请求，但没有想到资源，所以

PATCH /collections/123/items/

拥有这样的 body

[
  {'id': 1, 'order': 3},
  {'id': 2, 'order': 1},
  {'id': 3, 'order': 2}
]

但是，如何处理这种批量类型的请求的错误？当某些更新部分成功时，如何发送响应？是否允许修补集合而不是资源？如果这是错误的思路，更好的方法是什么？

Answer 1

首先，回答你在最后一段中的问题:

1. 如何处理批量请求中的错误很大程度上取决于请求。就您而言，我认为不应允许部分成功，您应该回滚整个操作并返回错误，因为失败的唯一原因是有人处理过时的表示。例如，当您批量创建或删除资源时，可以接受部分成功。

2. 您可以使用 207 多状态 HTTP 代码处理批量请求中的错误。它是一个 WebDAV 代码，但现在已经相当标准了。响应应该是一个文档，其中包含每个项目的详细 HTTP 状态代码和消息。

3. 集合也是一种资源，因此将 PATCH 与集合一起使用并没有本质上的错误，但是...

PATCH 请求应具有某种 diff 格式作为有效负载，确定要从中转换的状态以及最终状态。除非您愿意使用更标准化的格式，否则我不会使用 PATCH 来做您想做的事情。您可能想检查json-patch格式，在当前订单和所需订单之间创建差异，看看您是否喜欢该格式。例如，在您的情况下，它会是这样的:

[{"path": "/0/order", "value": 1, "op": "test"}, 
 {"path": "/0/order", "value": 2, "op": "replace"}, 
 {"path": "/1/order", "value": 2, "op": "test"}, 
 {"path": "/1/order", "value": 3, "op": "replace"},
 {"path": "/2/order", "value": 3, "op": "test"},  
 {"path": "/2/order", "value": 1, "op": "replace"}]

当然，如果客户端不关心当前订单，他可以删除test操作。您还可以使用 If-Unmodified-Since 或 If-Match header 添加前提条件。

您可能注意到上面的格式是完全通用的，并且与您正在更改的资源没有直接耦合。您可以以通用方式实现上述内容，并在 API 中任何需要的地方重用它来实现 PATCH。

无论如何，你的情况很简单，我会通过使用另一个资源以简单、平面的格式来完成订单。像这样，返回当前顺序的 id 列表:

GET /collections/123/items/ordering

[1, 2, 3]

您可以通过以下方式更改顺序:

PUT /collections/123/items/ordering
[2, 3, 1]