`health` link relation

[pmhsfelix]

It would be interesting to also propose a health link relation (or similar). I imagine a scenario where service responses include a Link header with it

Link: <https://example.com/monitoring/health>; rel="health"

This link relation could also be used on application/json-home representations

{
  "api": {

  },

  "resources": {
    "health": {
      "href": "/monitoring/health"
    }      
  }

}

This would be a nice way to improve discoverability.

[dret]

On 2018-01-16 15:10, Pedro Felix wrote:

It would be interesting to also propose a |health| link relation (or similar). I imagine a scenario where service responses include a |Link| header with it

|Link: https://example.com/monitoring/health; rel="health" |

This link relation could also be used on |application/json-home| representations

|{ "api": { }, "resources": { "health": { "href": "/monitoring/health" } } } |

This would be a nice way to improve discoverability.

all very much agreed. since it's older than this draft, it's not called "health", but "status" to me sounds a bit nicer anyway, and has been proposed here a little while ago:

https://tools.ietf.org/html/draft-wilde-service-link-rel-04#section-6.4

[inadarei]

Yeap, I think Erik's "status" link rel would be the one. We should reference it somehow from this spec.

[dret]

On 2018-01-17 03:35, Irakli Nadareishvili wrote:

Yeap, I think Erik's "status" link rel would be the one. We should reference it somehow from this spec.

maybe time to update that draft and possibly try to finish it; it has been in the pipeline for quite a while...

[inadarei]

@TODO: reference status link rel from the spec.

[mogsie]

Have you considered using well-known URIs (with associated registry) and include a registration for a well known URI /.well-known/health ?

[inadarei]

Since the RFC defines content format and not the address (e.g. in Kubernetes the format would be used by two endpoints for liveness checks and readiness checks), these kind of things may only be defined in an FAQ section of the RFC as the additional suggestions.

That said, speaking of well-known URIs specifically, the spec has been standard for over 8 years but I personally haven't seen it in common usage. Is it just me? What are some prominent usages of well-known URIs that you know?

[mogsie]

Off the top of my head ACME Challenges stands out as the one big success story. The well-known registry itself has numerous entries, so presumably it's being used, but like with ACME challenges, in places where we don't notice.

Registering a .well-known name is just a nice way of "getting out of the way" of the primary namespace of the host, and might ease discoverability by way of a management server simply ask GET /.well-known/health without having to discover the resource URI; an origin is enough. Either it gets an application/health+json document, or it doesn't.

[dret]

On 2018-12-06 03:17, Irakli Nadareishvili wrote:

That said, speaking of well-known URIs specifically, the spec has been standard for over 8 years but I personally haven't seen it in common usage. Is it just me? What are some prominent usages of well-known URIs that you know?

this may be intentional. the idea of well-known is not so much to standardize a naming pattern, because that would cause a flood of registrations. the idea is to solve discoverability in cases where it is not possible or reasonable to discover resources through other means such as links. my guess is that a well-known "health" registration would be met with some skepticism, as for APIs, it seems easily possible and even advisable to make health endpoints discoverable via links.

the "status" link relation just made it through its last-call reviews and will become RFC early next year. my recommendation would be to strongly encourage healthcheck resource discoverability through "status" links in key API resources, such as an API's home document.

[mogsie]

I am not arguing against using links to discover the health of a system, because I do recognise that an API might want to link to a health resource to allow clients of that API to react accordingly. (For example, api.example.com might have a link to health.example.com/api to report on the API's health.)

However, I also see situations where you have a large set of heterogeneous components (e.g. APIs, web pages, caches) that might have little in common when it comes to media types (home documents), but that might all (because of an internal service policy) expose some notion of health using application/health+json. Having to go through some home document to look for the health resource seems wasteful, since these various services might have different "home documents", some might not even have room for a home document that supports a link with this relation.

If this spec registered health in the well-known registry, it could make it a lot easier to deploy health checks to a lot of components where linking does not make sense.

[dret]

On 2018-12-06 12:00, Erik Mogensen wrote:

If this spec registered |health| in the well-known registry, it could make it a lot easier to deploy health checks to a lot of components where linking does not make sense.

again, my understanding is that well-known was specifically defined to make site-wide information available (with the canonical example being the robots.txt scenario). while not all APIs will use links, i think it is practical for pretty much any API style and technology to define how to discover their status info.

in many cases, i would even expect that the well-known assumption of one resource per site might not be a great fit for APIs. but it may actually be a good fit for actual web sites, but these can of course just link to their status page as well.