API Status Page Response Codes

Question

(This is sort of an abstract philosophical question. But I believe it has objective concrete answers.)

I'm writing an API, my API has a "status" page (like, https://status.github.com/).

If whatever logic I have in place to determine the status says everything is good my plan would be to return 200 OK, and a JSON response with more information about each service tested by my status page.

But what if my logic says the API is down? Say the database isn't responding or something.

I think I want to return 500 INTERNAL SERVER ERROR (or 503 SERVICE NOT AVAILABLE) along with a JSON response with more details.

However, is that breaking the HTTP Status Code spec? Would that confuse end users? My status page itself is working just fine in that case. So maybe it should return 200? But that would mean anyone using it would have to dig into the body looking for a specific parameter to determine the API's status vs. just checking the HTTP Status Code. (Also if my status page itself was broken, I'm fine with the end user taking that to mean the API is down since that's a pretty bad sign...)

Thoughts? Is there official protocol on how a status page should work?

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Answer 1

For me the page should return 200 unless has problems itself. Is true that is easier to check the status code of a response than parsing but using HTTP status codes to encode application informations breaks what people (and spiders) expect. If a spider passes for your page and sees a 500 or 503 will think your site has a page with problems, not that that page is ok and is signaling that the site is down.

Also, as you notice, it wont' be possible to distinguish between the service is down and the status page is down cases, with the last the only one that should send 500. Also, what if you show more than one service like the twitter status page ? Use 200.

Related: https://stackoverflow.com/a/943021/1536382 https://stackoverflow.com/a/34324179/1536382