Suggest default path /health

[christianhujer]

While the example suggests to the observant reader that it is a good idea to use /health as the default path to reach the health check endpoint, this is not mentioned anywhere in the text. May I suggest that the following paragraphs are added:

For interoperability, discovery, and ease of setup of tools that consume such an endpoint, health check endpoints SHOULD be reachable via a URL path that ends on /health. Preferably that path is reachable from the toplevel.

I'm sure the wording can be improved, but I guess you get what I mean.

[derekm]

MicroProfile Health is adding liveness and readiness checks on top of health checks.

Given status code expectations and coalescence of health check outcomes, additional /health/live and /health/ready endpoints are being proposed.

See Kubernetes for liveness and readiness definitions, but, basically, readiness failures pull the app out of loadbalancer rotation, and liveness failures kill the app instance in favor of a new instance.

[inadarei]

The decoupling of the wire format, described in this RFC, from the URI endpoint that it can be used at is intentional. For instance, in case of Kubernetes liveness/readiness checks both of those endpoints can use the format defined in the RFC. Which is what the reference implementation of the spec in Node does: https://github.com/inadarei/maikai#kubernetes-liveness-and-readiness-probes

The URIs health check endpoints are mounted to, in practice, are already so different, suggesting some specific URI in this RFC would probably be counter-productive. Case in point: Kubernetes itself doesn't even suggest a standard URI for mounting readiness and liveness probes, instead letting users indicate their own path.

[inadarei]

P.S. for making discovery of health check links easier, please see the existing conversation here: #5 and the suggested, arguably preferred way of doing it.

[christianhujer]

Status code expectations is another topic. Does /health always return 200, no matter what the value of health inside the JSON would be? I know this is not the right thread, but I somehow couldn't find the correct thread for that. Should I open a new thread for status codes?

Nonetheless, I think there's a lot of simple services which themselves would just have a single endpoint, and I think the RFC suggesting (not demanding) that endpoint to be "/health as long as there are no considerations to do otherwise" could be a good idea.

[inadarei]

Based on already-established behaviors, health endpoint is the conduit to the main API so it doesn't always return HTTP 200 when it itself can respond, health endpoints return HTTP 4xx-5xx if the main API is having trouble.

[christianhujer]

@inadarei Thanks for the clarification.

Just to make sure I'm 100% clear on this and on the same page as you, here's a use case. A middleware which talks to a backend. The middleware could have two health endpoints, /health for itself, and /backend/health for the upstream backend's health. That is, /backend/health on the middleware is effectively a gateway to /health of the backend.

Suppose the middleware is just fine, /health would return 200 with health: "pass".
Suppose the middleware knows it's in trouible, it would return 500 with health: "fail".

In the following, suppose the middleware is just fine.
Suppose the middleware can't reach the backend, /backend/health on the middleware would return 504 with health: "fail".
Suppose the middleware can reach the backend, /backend/health would just forward the response code and response body from the backend's /health endpoint.

Is that interpretation around how you intend health endpoints to deal with status codes correct?

[mogsie]

When it comes to suggestions of the response code, I would welcome something along the lines of suggesting to use 2xx responses when the system is in a "pass" state, and an error state (5xx) when the system is in a "fail" state. For "warn" states, it would be up to the system what health to indicate to the world. Typically load balancers have a "health check" that they check every few minutes, and "warn" might not be a good enough indicator to move traffic away from the service.

[inadarei]

Currently the spec defines "warn" as 2xx, meaning - load-balancers would NOT move traffic away, unless they dig deeper and investigate what the warning is about. If they do not understand as much (old, less "intelligent" networking tooling), by definition they should interpret warn as "ok", since it is not a problem yet. Which is why 2xx is suggested as the return status of "warn".

[mogsie]

Ah, I completely missed that part of the spec! 👍

[kalexmills]

Sorry to resurrect this, but I work on REST APIs for a healthcare company, and it is not unlikely that a /health endpoint may be needed for some other purpose at a point in the future.

I would suggest standardizing on a token which indicates the purpose of a health-check, but is somewhat less likely to be used as part of a public-facing API. I have begun using /healthz for this purpose. It declares its intent, and the intentional misspelling means that it is not likely to be needed for a public API.

[unRob]

Same as @kalexmills and we were wondering if an addition to .well-known i.e., /.well-known/health/?* would be the path to go. Unsure of possible ramifications or if its the intended use of the linked RFC.