4

I apologise if there is an answer for this already. I found related questions (e.g. HTTP status code for a partial successful request) but not exactly the same.

I'm building an API that returns data that is aggregated from multiple sources. Sometimes, some critical part of the data is unavailable and the client has to be made aware and error data is included in the response.

Other than the severity of the missing field(s), the rest of the resource is valid and useful and could be regarded as a partial update (e.g. if you only had permissions to see part of a resource).

So far, the options are

  1. return 200, consider it a partial resource, handle the error data fields in the application as you would with any other data
  2. return 207 to emphasise it's not fully successfully, but 207 is not strictly HTTP.
  3. return 500 and handle the successfully returned data in the application as you would on a 200

I'm partial to option 1 but I'm not fully convinced. Is there a clear way of handling this? Perhaps defining a specific content-type?

Community
  • 1
  • 1
guioconnor
  • 414
  • 3
  • 14
  • Its subjective, personally I would say 500 is appropriate as the data is erroneous in that it does not meet the expectation of the corresponding request. You can add whatever custom response headers you like, e.g. `X-Response-Type: partial` and instruct your clients to refer to the value before processing the response data if they receive a code 500 – Alex K. Jan 11 '17 at 11:34
  • Hi @AlexK. I can see the case for a 500, but since we're specifically handling the absence of the data in a useful manner and the resource can (and is) returned in a consistent way, a 200 would be more appropriate. If you want to draw a parallel I would say it's similar to a handled exception, in code, whereas the 500 would be analogous to an unhandled exception. Maybe it's not a good parallel to make? We are returning a content-type that highlights the information is partial to alert the client. Does this make sense from your POV? – guioconnor Jan 11 '17 at 14:47
  • Personally, I would return `200` and indicate what data is missing in the response body (your option #1). REST, as far as I know, is very resource-centric and, since in your case the resource is **valid and useful** (and, in other words, "it exists"), `200` seems to be the best choice. It's also probably not a good idea to fool with `content-type` as this may confuse some clients. Just go with plain `application/json` (or XML). I also notice that a lot of APIs tend to "err" towards `200` and return rich statuses as data. Seems more "idiomatic" this way. – sigriston Jan 13 '17 at 15:41

1 Answers1

3

You are missing the point here because a 500 is indicative of a failure of the system or the chain of communication, and since data is returned then it must be assumed that the resource exists and is found. What the OP has indicated is a partial result, implying composite data pertaining to the resource. This is necessarilly outside of the scope of http, which has done its job via a successful 200, unless you have elected a contract under which partial data is erroneous and thus a 40x.

Richard Green
  • 46
  • 1
  • My thoughts exactly, however (I guess I could have been clearer on my question) the system depends on data aggregated from multiple sources and individual fields may be missing due to unavailability of the sources for random reasons. In other words, a failure on the chain of communication. The question is, on a complex aggregation system, where these failures could be common, what would be the right status code to return. – guioconnor Jan 18 '17 at 21:54