Restful PATCH in the collection to update the sort option in bulk

Question

We have a large list ("collection") with several objects ("elements"). All this is managed through the RESTful interface. Elements are sorted manually using the order property on the element. When requested, the database lists all the elements in the collection based on order.

Now we want to expose this mechanism to users, where they can update the complete sorting of all elements in one call. The database does not allow the same order to be used for the same collection_id (unique collection_id + order ), so you cannot (and definitely should not) update all elements one at a time.

I was thinking about a PATCH request, but not a resource, so

 PATCH /collections/123/items/ 

With a body like

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

However, how do you handle errors for this bulk request? How do you send a response when some update has passed partially? Is PATCH allowed to collect instead of a resource? If this is the wrong line of thought, then which approach is better?

Answer 1

First, answering your questions in the last paragraph:

• How to handle errors in bulk requests depends on the request. In your case, I believe that partial success should not be allowed, and you should roll back the whole operation and return an error, since the only reason for the failure is the one who is dealing with an outdated view. For example, if you create or delete resources in bulk, this is great to accept partial success.

• You can handle errors in bulk requests using the 207 Multi-Status HTTP code. This is WebDAV code, but it is pretty standard. The response should be a document with detailed HTTP status codes and messages for each element.

• A collection is also a resource, so there is nothing wrong with using PATCH with a collection, but ...

A PATCH request must have some kind of diff format as a payload, defining the state you want to switch from and the final state. I would not go with PATCH for what you want if you do not want to use a more standardized format. You can check the json-patch format, create the difference between the current and the desired order and see if you like the format. For example, in your case it will 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"}] 

Of course, if the customer does not care about the current order, he can delete the test operations. You can also add a prerequisite with the heading If-Unmodified-Since or If-Match .

You probably noticed how the format above is completely general and does not have a direct link to the resource you are changing. You can implement the above in general terms and reuse this to implement PATCH wherever necessary in your API.

In any case, your case is simple enough for me to do this, having a different resource with order in a simple, flat format. Something like this, returning a list of identifiers in the current order:

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

And you can change the order:

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