Question

I’m working on a new REST-ful API who’s primary/only consumer will be a smart/non-web-browser client. I have a collection resource that is maintained/updated by background processes, not by the client itself. The only content type needed for the first iteration is JSON. The URIs are something like:

• /items/ – Resource representing the collection of items.
• /items/123 – Resource representing the individual item with ID 123.

Although the client will not be creating new items, or updating the collection to add/remove items, it will be updating some of the values in the individual items. My plan is to use HTTP PATCH to update item resources, using my own JSON patch format.

There will be many concurrent clients reading the items, and concurrent updates to different items, with occasional concurrent updates to the same item, and although a certain degree of “eventual consistency” is allowed, I would like to design this in as “cache friendly” a way as possible. Reading the RFC for PATCH, I see that on a successful response to PATCH, the cache of the Request-URI should be updated with the response, if there is one. The question comes down to:

Do I:

A) include the full representation of the individual items in the /items/ collection resource JSON representation, and send the PATCH to the /items/ URI and include the item to update in the patch format?

PROS:

• This allows the client to not have to do N number of requests just to display the listing of resources
• lets any cache of items be invalidated when a client updates an item.

CONS:

• This isn’t as “clean” to me, as I’m not really updating the collection, but an individual item.
• This invalidates the cache of the whole collection, instead of the cache of the single item that changed.

OR

B) In the JSON representaiton of the resource collection, only include links to the items included, and have the client request the individual items after discovering which ones are in the collection. HTTP PATCH would be sent to the individual item URI (e.g. /items/123)

PROS:

• Caching of the collection and item resources independently. PATCH of an individual item can properly invalidate the cache of just that item.
• API is clearer, since you issue an HTTP PATCH on the specific item you want to update.

CONS:

• Does not allow for batch updates to items. This is not currently a requirement at all, and I don’t foresee it in the future, but only hindsight is 20-20.
• Requires the client to issue N+1 requests to display the full list of items.

Answer 1

I would go for B. But are you clients usually asking for all the collection (I mean do they need the collection) ? if not A option would be generating way too much traffic. And invalidation of cache occurs for all of the items (as they are in the collection).

If your clients mostly get the whole collection then A with a query param for the specific item is also an option.