REST API - should I request the whole list after updating a single entity?

Question

I have a web app, where client and server communicate via REST API. On the server I have URLS like

• GET /api/items/list - return the list of items
• POST /api/items - insert a new item
• etc

There is no pagination, all the items are displayed on the client at once.

The question is - after the client inserts a new item, should it request the whole list from the server or just add the entity to the local collection?

Why yes:

• If the items are sorted, adding a new item breaks the sorting. It's easier to get the updated list from the server, than sort on the client.
• The list might have been updated by someone else. Yet, refreshing a list after any modification to it alleviates the situation a bit, but not solves it.

Why no:

• Two requests per one user action means that the user should wait twice longer, which can be a problem if the internet connection is slow.

I believe, that what can be done with 1 request should be done with 1 request. Am I missing something?

Answer 1

If you're concerned about network load and the list is small, enhance the resource such that the GET response provides a Last-Modified.

For the POST request, augment the response based on an If-Modified-Since header (the client value of the list's Last-Modified). If the server detects the POST is out of sync via If-Modified-Since, update and return the list in the body, otherwise update return an empty body in which case the new item is managed locally and client code deals with sorting.

Either way, the POST response must return the current Last-Modified.

Answer 2

As with most things in software, it depends, mainly on what your user requirements are, if any of them are conflicting and if so, which one takes priority.

The first thing I wonder is what is the "/api/items/list" endpoint retrieving that would be different from just hitting "/api/items". Is this a different representation, maybe with only certain fields etc.. which is fine, but if it was just for sorting then I would consider any simple sorting by fields to be a client side concern and implement my sorting there.

My reasons for this would be to potentially improve performance with caching of the /api/items/list since anyone hitting that resource will warm the cache for anyone else along the route, regardless of how they want it sorted. Naturally you would set the cache interval to a suitable value.

If you consider it from the point of view of adding a new field to the item resource. Would you be able to implement "sorting" on that new field without a client update as well? You could but it would be rather more difficult than simply allowing the client to control sorting of the data.

With regards to being aware of concurrent updates to the list, again depending on whether you want millisecond updates (probably shouldn't be using HTTP if this is true requirement) or if a few seconds is fine. If your system just wants to be able to check the list has been updated with 5 seconds, implement an endpoint which can be polled to see if the collection has been updated or not, and then retrieve the list if it has. Again, if caching is implemented, chances are in a multi-user environment someone else might have also been watching the same collection and has just warmed the cache for you, saving you a round trip to the server.

If your item resources have a "last modified" field, then it would be quite easy to implement a resource like [GET] "/api/items/modifiedTimes/latest" which represents the most recent modifiedTime of whatever the server considers to be the latest resource. If your worried about two updates occuring with exactly the same timestamp, then use the same concept but solve it a different way.

In summary, if you are using HTTP with all it's goodness such as caching, worrying about the overhead of two round trips versus one to the server isn't worth considering, unless, again it depends. If latency and performance really is an issue, then it is in direct contention with the requirement for server side sorting and you need to compromise.

POST the item to the collection, server should return Created with no body. On the client add your item to the collection and reapply your sort. In parallel have something polling the latest endpoint to check if the collection has changed, and get the list if it has.

As an aside, if you were really really worried about performance, you might consider instead of polling a latest endpoint with the time, having an event endpoint to poll that can return you a list of events that have occurred on the collection (insert, update, delete) along with a payload for each event where required. Something like "/api/items/events?since=2017082215005959" You could use this result to update your client list as needed.