Error handling

[Larry Garfield]

Interesting concept.  My key question is what qualifies as "fully operational"?  If a site is working fine for most people, but, say, there's a library that's out of date, or an update is needed, or one particular service is down but not others... which of those qualify as "not fully operational"?  And what error code should be returned then?

System status is not a binary state.

And of course there's the point that a properly RESTful system doesn't care about specific URLs blah blah... :-)  But what of services that are not hosted at the domain root?

--Larry Garfield

[Brett Swift]

I think the goal of this should be clearly identified.  Each service would need some sort of documentation on what it is covering in it's health check.   No documentation might indicate that  "my web container is responding". 

For Service API's  in our enterprise, we include a service version - which is mostly helpful in a non-prod environment,  and unless you have a large cluster, or multiple versions running in production,  it's not as useful in prod. 

For one of my projects,  there is a database,  message queue server,  and workflow engine that I would have to check.   Something like this may make sense: 

{

    "apiVersion": "1.1.0",

    "last_updated": "2012-12-11T08:14:17Z",

    "status": "good",

    "healthChecks": {

        "db": {

            "last_updated": "2012-12-11T08:14:17Z",

            "status": "good"

        },

        "queueServerConnectivity": {

            "last_updated": "2012-12-11T08:14:17Z",

            "status": "good"

        },

        "workflowEngine": {

            "last_updated": "2012-12-11T08:14:17Z",

            "status": "good"

        }

    }

}

... where the stuff in grey isn't part of the standard - but more for informative purposes. 

The root $.status   tag would be a roll-up of all the other status versions, but the service itself would determine that.   If a service wasn't ok, you could browse to the status endpoint to determine what was wrong, but a machine wouldn't be reading that for you. 

Then for the standard you would just need to define your status types.   "ok","nok".   That way the standard remains generic and the services themselves really solve the problem that you mention Larry, about "System status is not a binary state".