In the modern age of the Internet, APIs are everywhere, and with good reason. They're an indispensable tool for developers and businesses alike.

A good API allows teams to build fantastic software at speeds once unimaginable. You don't need to build everything you need from scratch. Other people have solved many common problems, so you don't have to. APIs for functionality like payment processors or user identification is particularly useful to avoid the security hazards in these fields.

Many organizations nowadays rely on APIs to run critical functions for their business. Not only do they use third-party APIs, but also home-grown APIs. Applications can have public APIs for their customers, or internal APIs for their in-house services.

Because APIs are a crucial tool, they're expected to be up and running in peak condition at all times. Having an API perform poorly or go out of commission for any reason can disrupt business in a major way.

If your organization maintains an in-house API, how would you go about testing that it's working well?

The ping approach is not enough

In organizations I've worked for, the most common test I've seen for checking an API is to send a request a pre-defined endpoint and review its response. Often, the request doesn't send any additional data, while the endpoint returns a simple response. I call this the "ping" approach.

For instance, a REST API might have an endpoint at /ping. The endpoint receives a GET request with no parameters. If everything works as expected, the response is an HTTP status code of 200 OK, meaning that the call was successful. Any other HTTP status code or a timed-out response sends out an alert for the development team to investigate.

While the ping approach gives you an indication that the API is running, it's a terrible way to test an API. I've seen APIs where a pre-defined "ping" endpoint works perfectly well, but everything else is broken.

When testing an API only to check if it responds to something, you risk missing whether its internal services are still working well. These types of "ping only" endpoints usually don't interact with services like a database or queue. That means if one of those services is down, you wouldn't know for sure.

Also, since the pinged endpoint often returns an HTTP status code with no body, it doesn't give you a clear picture of performance. Returning a simple "OK" response is usually fast. If a service that the API relies on is causing a bottleneck, the "OK" response won't reflect that.

At this point, you might think that all you need to do is to send more requests to different endpoints and verify the results. This approach can work, serving as a regression test suite. However, running an entire test suite is time-consuming, and it's simply not the right tool for checking the health of your system.

Enter the health endpoint

The best way I've found to have a quick and easy check of your API is with a health endpoint. In simple terms, it's is an accessible endpoint that tells the system to run a check on essential services and display the results in a readable manner.

A health endpoint is an integral part of some systems, such as a system consisting of microservices. It's a typical pattern for that type of architecture. But it's also highly useful for testing purposes as it returns valuable information to verify things are running smoothly.

These kinds of endpoints not only tell you that your API is up and running, but it should also contain additional information to determine the state of the system. Some information that your health endpoint can return can be:

• The state of the system's database cluster to ensure that it's running.
• Stats from your job queue to check jobs are processed correctly and on time.
• Status checks for external services that your API requires to work correctly.

Many popular open-source products contain health checks, providing insight into their functionality. The distributed search engine Elasticsearch has a Cluster Health endpoint displaying the health of your cluster. Service networking tool Consul has a Health HTTP endpoint returning the status of different nodes in your system architecture. Message broker RabbitMQ has monitoring endpoints with vital stats like memory limit alarms and message publishing rates.

Keep a finger on the pulse of your API

If your API doesn't have an existing way to check health stats, I'd highly recommend creating an endpoint for this purpose. Of course, this depends on your application and needs. Get your development team involved for better insight on what checks are needed to ensure the API's health.

Once you have an endpoint implemented, make sure you use it. If your team has an in-house monitoring system in place, include an API health check there. If you don't have an existing monitoring framework in place and don't have the resources to build one, there are plenty of external services you can use:

• Runscope has API monitoring that checks uptime, performance, and data validation.
• Postman allows you to set up monitors that make sure your API is running as expected.
• SmartBear's AlertSite service can help you automate monitoring by using existing SoapUI tests or Swagger files.

Regardless of which tool you use, make sure you're frequently using it to verify your API. Check the data that matters the most to you, and raise alerts to the right people as quickly as possible.

Avoiding common pitfalls with the health endpoint

Health endpoints are useful but can come with its share of pitfalls if implemented or misused. Here are a few common mistakes your team can run into with a health endpoint:

• Not using it correctly or at all. As already mentioned, you need to use your health checks as frequently as possible. You also need to make sure you're monitoring its response for what matters most for your API to work at optimal conditions.
• Having insufficient information returned. Your health check should give you a clear picture of how the internals of the API are doing. For example, if your API relies on a service to be up and running and that service is not exposed publicly, run a check on it and return its status.
• Developers can't/won't implement a new endpoint. There are many reasons why your development team can't or won't implement a health endpoint. They might have a tight schedule or looming deadlines, or don't have enough qualified people available to work on this. These situations require an open dialog - stress the importance of maintaining a healthy API and discuss options for implementation.
• A third party provides the API. Often, APIs are provided by a third party, meaning your team doesn't have access to implement any new functionality. In these cases, you'll probably have your hands tied. The best you can do is implement your own monitoring. You won't have as much insight into the API, but it's better than nothing.

Conclusion

Your API is important, or even mission-critical for your business. You need to take the steps necessary to make sure it stays in good shape.

Don't merely ping an endpoint to see if your API is running. You also need to take care of what's happening under the hood. Take a look at the services your API relies on too. Creating a health endpoint and frequently monitoring it keeps your API happy and healthy.

What measures do you or your organization take to ensure that your API is running at peak condition? Are there other ways to handle health checks to APIs that I didn't mention? Leave a comment below - I'd love to hear your insight.

Photo Credit: Hush Naidoo on Unsplash