Introduction

Implementing a health check API provides a fast & easy way to test your application.

If your health check API returns an expected value, you know that the server is running & accepting requests. This simple test establishes that your server is healthy, just like the name suggests.

Health Check API

The health check API is used to test the health of the running server. The API is implemented as a simple request -> response function that listens at an end point you define in the function inside the server code.

Let’s take a look at how this works.

The Code

A health check API endpoint doesn’t need much beyond a function that consumes an incoming HTTP request (req) and produces an HTTP response (res).

Typically, the response object is used to send a message or status back to the caller, which could be either a human using a web page or curl command or a piece of automation that is monitoring the application and which uses the response to assess the health of the back end. That’s the source of the name health check.

Here is a simple health check API implementation as part of a node.js application server:

app.get('/api/healthcheck', function (req, res) {
	res.write('The server is running\n')
	res.end()
})

The API uses the HTTP GET verb.

A GET function supports a simple incoming request, i.e. one with no body data such as in a POST. You could define request parameters that perform additional logic, but that’s unnecessary for a basic health check. Get is typed lowercase in the code because that’s how the method is implemented inside the http library. Using uppercase GET will result in an error message stating app.GET is not a function when you start the server.

You could use an arrow function instead of using ‘function (x, y)’ notation. Arrow functions may be easier to read for developers who learned that technique.

When this health check API is included in the server’s code, an HTTP endpoint is provisioned that listens at the port defined for the server using the URI:

[server:port]/api/healthcheck

For example, if your local development server is defined to run on port 8080, then your URI will be

http://localhost:8080/api/healthcheck

A production server implementation would use a real DNS-resolvable name rather than localhost.

If your server is running it will return a response in the browser that looks like this:

You don’t need to use a browser. A curl to that endpoint returns the same repsonse.

/Users/jbminn\>curl http://localhost:8080/api/healthcheck
The server is running

Finally, there’s nothing special about the endpoint name I’ve used.

I like to scope all my APIs with ‘/api/[something]’ so that it’s apparent what this implements. The use of ‘/api’ in the name is just a convention.

It could be anything, as long as it matches what you defined in your server. This is a silly example but it makes the point:

/Users/jbminn\>curl http://localhost:8080/flubber/hoho
The server is running

Up Next

I’ll cover setting up a node.js project: installing & using nvm, node modules and helpful coding techniques.