How should exceptions be handled in a RESTful API for collection results?

Question

We are designing a RESTful API to return collections of documents. Our initial implementation uses HTTP status codes to indicate if a request could not be fulfilled. This seems to be a widely accepted best practice (see for example here).

We recently ran into an issue where a user was pulling 1000 documents. One of the document retrievals failed, and thus we returned an HTTP 500 status code.

An alternative would be to return an HTTP 200 status code with the payload having the 999 documents that we were able to retrieve, and then an error collection indicating the one that failed.

Is this alternative approach a violation of RESTful principles? How should this situation be handled? Are there any options besides these two approaches?

Answer 1

Yes, I think it is perfectly acceptable as long as you document that the data that you are returning, can contain an "error" collection. This means that whatever semantic media-type you are using to describe this collection of documents, should have documentation that describes what the collection of documents should look like, and what the error collection should look like. The client can then decide what to do with this information.

For example, if you are returning this as JSON (just an example), you may have a media type like application/json+documents or something, which could look like this:

{ data : {
    documents: [ ... ], //document objects
    errors: [ ... ] //error objects
}

You would then have documentation that describes what the documents look like, and what the errors look like. In truly RESTful API's it is the media-types that are documented and not the calls, because in a truly RESTful API there is only one endpoint, and everything else is "discovered" via that initial endpoint, in conjunction with semantic media-types. So as long as you document that errors are possible, and you describe the format that the errors will be delivered, you should be alright.

This is also isn't an "exceptional" condition since it seems to be in your case that it is foreseeable that a client may not be able to retrieve all documents. Hence it is alright to inform the client of that fact.

Answer 2

There is a line that you sometimes have to cross in a unique situation like this: involving the user.

It's not unreasonable to notify the user that the payload is too large, and return an internal server error.