You can read this article by Scott Hanselman if you want to learn more about it.

I’ve been dying to use this on all my projects but there was one problem – It was not included in our generated OpenAPI specifications.

So I headed over to Swashbuckle.AspNetCore, which I use to generate OpenAPI specs, and found this nice feature request!

Unfortunately, the mechanics of health checks are totally different and not easy to integrate so it’s up for grabs.
That doesn’t really help me for now, but what’s the issue anyway?

Why OpenAPI specifications are important

When building APIs, it is crucial for me that every endpoint is documented with OpenAPI specs.

There are a couple of reasons for that:

• You are ready if you want to use an API Gateway where you can import those to expose them via a more robust API platform
• It improves the customer experience when consuming your services as they guide you through your application
• It acts as living documentation elaborating on what features the API provides

One could say that health endpoint is different because not everybody should consume it! That is correct, but those that will use it still need to know how to call it and what to expect, so you have to document them as well.

So I started digging…

Recently I started a new project and I was sick of adding my own health point again, so I started digging!

It turns out that when you call AddHealthChecks it adds a HealthCheckService as a dependency.

This allows you to call all the configured health checks and get a report of their status.

A simple trick of dependency injection, et voila:

It’s still a bit verbose but it’s perfect for me – Not only can I now document my health endpoint, but it also allows me to delegate health checks to the framework.

It looks silly but saves me a lot of trouble.

How about non-HTTP applications?

One downside of the ASP.NET Core’s health checks is that it’s limited to HTTP only, so if you are building a queue processor you have to write your own TCP-based health check. This is not an easy thing to do and would be great if this comes out of the box allowing us to choose how to expose it.

Frankly, this is a big gap because there are a lot of applications which can benefit from this where people don’t even bother to implement it themselves because it’s too much work.

Now that the container world is booming it is even becoming more and more important – Health endpoints are used, for example, to check if the app is still running fine; if not they kill it and start a new instance! But what if you don’t have those endpoints and the processor goes into an unstable status, nothing will be processed anymore.

The good thing is that it’s already on their radar, but unfortunately not coming very soon.

Conclusion

Health endpoints are essential for building operable platforms, they allow you to gain insight on how your application is doing and if it’s ready to serve traffic.

We’ve learned how we can provide a well-documented health endpoint which is served by health information provided by ASP.NET Core.

Thanks for reading,

Tom.