Response body for health checks

[steve-chavez]

Problem

Currently the health checks don't have a response body. It's sometimes surprising to do:

curl localhost:3001/ready

And have it return nothing

Solution

There's an RFC draft (already expired) which defines an application/health+json media type:

{
  "status": "pass",
  "version": "1"
}

We could adopt that. Having version there is also useful because:

• Proxies can rewrite the Server header we use for exposing our version, thus our version is lost there.
• Parsing the whole OpenAPI for the version is cumbersome.

References

• https://blog.frankel.ch/healthcheck-http-apis/

[wolfgangwalther]

If we can adopt any kind of versioning support (of the API, not PostgREST!) via schemas or so.. then I'd want the API version to be exposed here and not the PostgREST version, I think. But not sure.

[steve-chavez]

Hm, the RFC also defined a releaseId.

releaseId: (optional) in well-designed APIs, backwards-compatible changes in the service should not update a version number. APIs usually change their version number as infrequently as possible, to preserve stable interface. However, implementation of an API may change much more frequently, which leads to the importance of having separate "release number" or "releaseId" that is different from the public version of the API

Maybe we could use that for the postgREST version.

[wolfgangwalther]

Hmm - not really. When I update PostgREST with a major bump, the API might change in a breaking way. To do proper versioning, I would need to bump my API's version when updating PostgREST - aka the PostgREST version is "a part of" the API version.

release number seems more fit for something like a git hash (of my API's git repo).

[steve-chavez]

The RFC has a checks field, which we could use for:

{
  "status": "warn",
  "checks": {
    "schema_cache": "stale"
  }
}

Also, there's a status value of warn on the RFC

"warn": healthy, with some concerns.
In case of the "warn" status, endpoints MUST return HTTP status in the 2xx-3xx range, and additional information SHOULD be provided, utilizing optional fields of the response

[steve-chavez]

Looks like the RFC is expired and no longer receiving updates inadarei/rfc-healthcheck#78