8

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?

Vivin Paliath
  • 94,126
  • 40
  • 223
  • 295
Joe Alfano
  • 10,149
  • 6
  • 29
  • 40

2 Answers2

2

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.

Vivin Paliath
  • 94,126
  • 40
  • 223
  • 295
  • Thanks Vivin for the input. So I guess a possible dividing line is if the situation is considered "exceptional" or not. If it is, then an HTTP 500 status should be returned. If the situation is not exception and can be expected to occur regularly as part of normal use of the API, then perhaps an HTTP 200 is more appropriate, sending the error information in the (well-documented!) payload content. – Joe Alfano Apr 16 '13 at 19:21
  • @JoeAlfano Correct. If it is an *actual* exception that they user cannot really recover from, then an HTTP 500 is fine. Otherwise, you can provide whatever partial data you have, along with the errors and the user can decide how to handle that. – Vivin Paliath Apr 16 '13 at 20:38
1

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.

jakenberg
  • 2,125
  • 20
  • 38