3

I know someone who is writing an API, and wants to use HTTP status codes to report the outcome of queries. e.g. if the user calls example.com/api/product_info?product_id=X, and the product doesn't exist, it would return HTTP status 400: Bad Request. I think that, since this is a valid call (i.e. the actual HTTP request is not malformed), it should return a 200 code response, and just have the body of the response something like {status: 'error'; message: 'No such product'}.

So my question is,

1) Is it appropriate to use HTTP status codes to convey non-HTTP program state, as in the example above?

2) Is there some standard, or at least widely used, specification describing when HTTP status codes are appropriate for use?

Benubird
  • 18,551
  • 27
  • 90
  • 141
  • I think 404 would suit better to your case when client asks product resource which doesn't exists. You should return 4XX or 5XX when something isn't going as it should. [This](http://stackoverflow.com/questions/27921537/returning-http-200-ok-with-error-within-response-body/) could be helpful. 2. [HTTP specification](https://www.ietf.org/rfc/rfc2616.txt) – FrAn Jan 16 '15 at 08:30
  • @FrAn Not sure this is really a case of the resource not existing. For another example, if the api call was `/setprice?product=X&price=Y`, what response would you return if product X exists, but Y is not an acceptable price (e.g $1 when the minimum price is $5)? Still a 404? – Benubird Jan 16 '15 at 08:36
  • In that case I would return 400 or 403 in this case client is trying to set price, but the price value isn't acceptable, not trying to GET the product so no 404. It is highly debatable issue. – FrAn Jan 16 '15 at 08:47

1 Answers1

2

I was actually just talking about this the other day - http://blogs.mulesoft.org/api-best-practices-response-handling/

Your status code should reflect the response of the API, as 200 is "OK" and should be used for data that is successfully returned. However, 201 should be used for created items.

As mentioned already, in the event where the user tries a call but it fails (ie: users/?id=5) the server could return back a 400 to inform the user that it was a Bad Request, or a 404 if the resource doesn't exist.

It also depends on the action - if they are searching for a user and there are no responses, I wouldn't return an error, just a 200 with no results found. However, if they are trying to do a PUT or PATCH on a user that doesn't exist I would tell them with an error- as chances are there's a problem within their application somewhere.

In the link posted above you'll find more status codes, but one of the biggest advantages to using status codes is that it informs the client just though the header what actually happened with the server. This allows them to do a relatively quick (and low memory) check instead of having to deserialize the body and loop through an array looking for an errors key.

Essentially, you're giving them the tools to quickly and easily understand what is happening- something that I think every (sane) developer appreciates.

Hope this helps! - Mike

Mike Stowe
  • 488
  • 4
  • 4