Designing APIs is an important task. The API should be simple, follow good conventions, behave like expected, be efficient. This post is about updating data in bunch operations.
Lets say you have a blog-system with many authors. On the back-end the authors have a list of all posts and pages. Now they can select many and publish all at once. It is also possible to select a few and change there rating. Actually I don’t want to talk about a blog system. It is about changing many items in a list.
In a standard RESTful-API it is the case that the client will send a patch-request for each of the items. This RESTful approach is simple to implement, in many cases the API can be generated almost automatically. For example you have a MongoDB or MySQL. Using sails.js or loopback you can easily expose an HTTP-REST-endpoint. Also on client side that API can be used very easy. Loop over the selected items, trigger the update-call and handle the response, one by one.
But as comfortable as it is it is also not efficient. When always sending the same information for different entries. In slow connections (mobile, village, shared internet, China), it can reduce the user experience. For this cases the server can provide additional methods to handle bunch operations. like publishPosts many, changeRatingTo. Both methods would in our case expect a list of postIds and the value to change to.
Having a list of Items to change on the server, you have the same question again. Do you execute a single update command on the db or one update after the other. Can you check the permission in as list-operation? Then you can decide, refuse all item-changes if one item fails with some precondition. Last is the result reporting. do you need to send success states for each item, only the success items, only the failing item-changes.
How ever the solution is, that you chose. You should give a transparent report to the user and update the item list accordingly. In the end I want to give you some questions you can ask, when you get the task to implement an API with list operation.
- can each item get a different value using this procedure?
- fail-one-_fail-all or detailed report?
- how should the error reporting look like?