集合上的静态PATCH可批量更新排序参数 [英] Restful PATCH on collection to update sorting parameter in bulk
问题描述
我们有一个包含大量实体(项目")的大列表(集合").所有这些都通过RESTful接口进行管理.这些项目可以通过该项目上的order属性进行手动排序.查询时，数据库会根据订单列出集合中的所有项目.
We have a big list ("collection") with a number of entities ("items"). This is all managed via a RESTful interface. The items are manually sortable via an order property on the item. When queried, the database lists all items in a collection based on the order.
现在，我们想向用户公开此机制，使他们可以在一个呼叫中更新所有项目的完整排序.该数据库不允许相同的collection_id(唯一的collection_id + order)具有相同的order，因此您不能(而且绝对不应)一一更新所有项目.
Now we want to expose this mechanism to users where they can update the complete sorting of all items in one call. The database does not allow the same order for the same collection_id (unique collection_id + order), so you can't (and definitely shouldn't) update all items one by one.
我想到了PATCH请求，但没有想到资源上的问题，所以
I thought of a PATCH request but not on the resource, so
PATCH /collections/123/items/
像这样的身体
[
{'id': 1, 'order': 3},
{'id': 2, 'order': 1},
{'id': 3, 'order': 2}
]
但是，您如何处理这种批量请求类型的错误?当某些更新部分成功时，您如何发送响应?是否允许修补集合而不是资源?如果这是错误的思路，什么是更好的方法?
However, how do you handle errors for this bulk-type of request? How do you send a response when some update succeeded partially? Is it allowed to PATCH a collection instead of a resource? If this is the wrong line of thought, what is a better approach?
推荐答案
首先，在最后一段中回答您的问题:
First, answering your questions in the last paragraph:
-
如何处理批量请求中的错误在很大程度上取决于请求.对于您的情况，我认为不应允许部分成功，而应该回滚整个操作并返回错误，因为失败的唯一原因是有人处理过时的表示形式.例如，当您批量创建或删除资源时，可以接受部分成功.
How to handle errors in bulk requests depends a lot on the request. In your case, I think partial success should not be allowed and you should rollback the whole operation and return an error, as the only reason for a failure is someone dealing with an outdated representation. When you are creating or deleting resources in bulk, for instance, it's fine to accept a partial success.
您可以使用207 Multi-Status HTTP代码来处理批量请求中的错误.这是一个WebDAV代码，但目前已经很标准了.响应应该是包含每个项目的详细HTTP状态代码和消息的文档.
You can handle errors in bulk requests by using the 207 Multi-Status HTTP code. It's a WebDAV code, but it's pretty standard by now. The response should be a document with detailed HTTP status codes and messages for each item.
集合也是一种资源，因此在集合中使用PATCH并没有错，但是...
A collection is a resource too, so there's nothing inherently wrong in using PATCH with a collection, but...
PATCH请求应具有某种diff格式作为有效负载，以确定要从其转换的状态以及最终状态.除非您愿意使用更标准化的格式，否则我不会选择PATCH来进行所需的操作.您可能需要检查 json-patch 格式，在当前和所需的顺序，看看您是否喜欢这种格式.例如，在您的情况下，它将类似于:
A PATCH request should have some sort of diff format as payload, determining the state you want to transition from, and the final state. I wouldn't go with PATCH for doing what you want unless you're willing to use a more standardized format. You might want to check the json-patch format, create a diff between the current and the desired order and see if you like the format. For instance, in your case it would be something like:
[{"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标头添加前提条件.
Of course, if the client doesn't care about the current order, he can remove the test operations. You might also add a precondition with the If-Unmodified-Since or If-Match header instead.
您可能已经注意到上面的格式是完全通用的，并且与要更改的资源没有直接关联.您可以以通用方式实现上述内容，然后在API中需要的地方重复使用它来实现PATCH.
You probably noticed how the format above is completely generic and has no direct coupling to the resource you're changing. You can implement the above in a generic way and reuse that to implement PATCH wherever you need it in your API.
无论如何，您的案例非常简单，我将通过以简单，扁平的格式安排订单中的其他资源来完成此任务.像这样，以当前顺序返回ID列表:
Anyway, your case is simple enough that I would do it by having another resource with the order in a simple, flat format. Something like this, returning a list of ids in the current order:
GET /collections/123/items/ordering
[1, 2, 3]
您可以通过以下方式更改顺序:
And you can change the order by:
PUT /collections/123/items/ordering
[2, 3, 1]
这篇关于集合上的静态PATCH可批量更新排序参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
