Rest – Bulk update: return all results or only failures

api-designrest

I'm developing an API that performs bulk update of a large number of items in a single call. This code will consist of a REST endpoint and the internal library code that it calls.

There are a few reasons why the update of a specific item may fail (e.g., the item has been deleted). The question I'm debating is how to return the result to the caller.

I'm leaning towards returning a collection that contains only the items with failures, but I could see scenarios where it would be helpful to return the result for all of them.

In either case, the response would contain a collection of objects like this:

class UpdateResponse
{
    int ItemId;
    ResultType Result;
}

Where ResultType is an enumeration that describes the result of the update.

Is there any compelling reason to choose one strategy over the other (return all vs. return failures)?

Best Answer

You have two options. Either to use the 200 OK or the 207 Multi-Status.

I would not recommend to use the latter, as it is a WebDav status code (WebDav is an extension of HTTP) status code that forces you to respond with an XML document. Although it allows you to use multiple status code in your response.

My preference would goes to the 200 OK because it basically means: "yes your request has been completed". That is your case.

The second question is a choice between: "your request has been completed: here is a summary" or "your request has been completed: here is what goes wrong". The real question is: does the client needs to know that an item has been successfully updated ?

  • Yes: provide all results.
  • No: provide only failures. It will avoid for a client to parse the entire response with unnecessarily information.