Add a heartbeat method to your service

Over the summer months I wrote a series of posts about designing APIs in general, and web services in particular. This included posts on status codes for web services, error feedback for web services, auth mechanisms for web services, saving state in web services and using version parameters with web services. I thought my series was finished but I thought of something that should have been included – perhaps the series will keep growing as I learn more?

I’ve worked with a couple of services recently that have a rather excellent feature – a method which calls the service but doesn’t do anything useful but simply lets you know the service is alive and well and residing at the location you thought it was. These “heartbeat” methods just allow consumers to check for signs of life, verifying that the service exists.

The heartbeat shouldn’t require any particular parameters or any authentication, since formatting data and passing credentials can be a stumbling block for those integrating with a service for the first time or those debugging issues. The heartbeat method can return some known data, perhaps an “I’m here” message, and maybe some version information. Flickr has a nice method flickr.test.echo which will also echo back any parameters that were sent to it – which could be useful for debugging values which don’t arrive at the server as you expected.

Another use for a heartbeat method is to allow monitoring systems to call a simple method, needing no credentials, and always get the same response back. Its not uncommon for these monitoring systems to be pointed at a particular page, and for failures to be indicated if the contents of that page changes (because data in the system changes, for example).

So – build a heartbeat service, you might never use it but when you need it, you’ll be glad you did!

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.