My last post described how you can use the API Science API monitor settings to configure what constitutes success each time your monitor is run. While your customers access your product on a 24/7 basis, your data center probably runs unattended during off-work hours. So, what happens if an API (internal or external) that’s critical for delivering your product to customers goes down (or awry, according to your monitor settings) during your team’s off-work hours?
Anytime your product is inaccessible, or it produces invalid or incomprehensible results, the customer experience suffers, along with your product’s reputation. Therefore, it’s critical for your team to know as soon as possible if a critical API has suddenly gone down or started to return invalid results. If this happens with an internal API, your software development team needs to get to work immediately, whatever the hour, to address the issue. If a critical external API has issues, it’s important for you to be able to notify your customers that your product is presently down due to issues with an external data feed — if you can do that, your customers will know your product is presently down, but they’ll also realize it’s not your fault.
API Science includes an option to alert your team whenever an API you monitor is down or fails to pass the tests you’ve specified in your monitor settings. Going to the Dashboard and clicking on one of your monitors will bring you to the summary status page for the monitor. At the bottom of that page (below “Uptime History”), there is an “Alert Rules” section:
In recent posts I’ve been working with the World Bank’s Countries API monitor I set up for our Acme API Monitors account. For this monitor, I request the information for Brazil from the API. In the monitor settings, I have configured a Regex Validation that searches for
wb:country id="BRA" in the response text each time the API is tested. This text will be part of the response if the API returned a valid response. My Regex Validation setting defines that if the specified text is not found in the response, the test should be marked as failed, regardless of whatever text was returned. That is, the API could return something (it’s still “up”), but if it does not return the information for Brazil, from our point of view, the API is nonfunctional.
If our product depends critically on retrieving the current World Bank Countries API information for Brazil, and we’re not receiving that, then someone needs to know right away. Here is where API Science alerts come into play.
The Alert Rules let you configure when and how an alert should be issued, when an API test fails:
- WHEN VALIDATION FAILS: select “If any call fails (connectivity issue or 5xx)”
- NOTIFY: select or add a contact to be notified
- ALERT ON UP: click if you’d like an alert to be sent also when the API test returns to success
- THRESHOLD: defines how many consecutive validation failures must occur before an alert is sent
In our Acme API Monitors demo, I configured our World Bank Countries API monitor notification like this:
then I clicked the “Add Rule” button to activate the alert.
The World Bank Countries API is generally reliable. As I write this, it’s been up for the past two days. But, to test the alerts I just created, I’ll edit my Regex Validation setting such that the next time the monitor is run, a failure should be detected. The monitor will still request the information for Brazil, but I’ll make the Regex validation search for
When I run the revised monitor, on the Call Summary result I see:
Going to my AcmeAPIMonitors Gmail account, I see a message from API Science with the subject line “API monitor validation failure: World Bank Countries” with details about the outage in the message body.
I clicked the alert box for a notification to be sent when the API test returns to “up” status. So, now I’ll edit the monitor, correcting my validation back to verifying that the information for Brazil was returned. I rerun the monitor, and the test succeeds. Rechecking my email, I see a new message from API Science with the subject line “API monitor service returned: World Bank Countries.”