HTTP status code for a boolean resource

Question

I have come to a dilemma whilst developing an API at work. Say I have a route for a resource as follows:

/order/:orderId/returnable

This resource is supposed to check whether an order can be returned to a shop or not. Right now it is replying a status code of 200 if it IS returnable and 404 if not.

A colleague rightfully pointed that the resource is not gone and that I should use a 200 for any response, and then respond with a body containing my results.

Both have their semantic meaning, and I don't see a clear winner.

What response status code should we use? And should there be something in the body?

Answer 1

Your colleague is right. From the spec (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5), it says 404 is when "The server has not found anything matching the Request-URI". In your case, the server has found something, which it needs to return. You'll need to define the syntax of the entity returned in responses to this API, and return HTTP 200. It can be as simple as a boolean value, or anything that makes sense as long as its documented.

If the given "orderId" does not exist, it should return HTTP 404.