Working with API Science API Monitor Settings

In an earlier post, we created a new API Science monitor that tests the World Bank’s Countries API. Our World Bank Countries API monitor was created using the minimum possible configuration: the monitor simply executes an HTTP GET for the URL: http://api.worldbank.org/countries/br

However, the API Science monitoring platform provides options for much more comprehensive configuration of API test settings, and also provides the capability for automated notifications when an API monitor test fails and, optionally, when the test returns to success.

To view the configuration settings for your monitor from your Dashboard, click on the pencil image in the right-most column (“Actions”) for the monitor:

dashboard-world-bank-row

This will bring you to the page for editing the monitor:

edit-world-bank-monitor

Click “Show Settings” to view the configuration options:

api-monitor-settings-initial

The Parameters section lets you add parameters for HTTP POST and PUT requests. You can add any number of Key/Value pairs. Note that, if the API is accessed using the GET protocol, the API may support direct insertion of parameters into the URL using the ?param1=value1 protocol. The World Bank’s APIs provide many opportunities for parameterized calls. Based on your customers’ needs, you could utilize the Parameters configuration to specify the exact World Bank API call you want to monitor.

The Headers section lets you configure HTTP header Key/Value pairs, for example Content-Type and application/json.

The Validations section lets you identify additional criteria (beyond the API having returned a response) for determining what constitutes a successful API test. Any combination of five different types of validation can be configured:

  • Response Code: you specify which HTTP Status Codes are considered to represent a successful test; if any other HTTP status code is returned, the test fails.
  • Regex: you specify a regular expression that must be satisfied in order for the test to be considered successful; if the Regex analysis of the returned stream fails, the test fails.
  • Validate JSON: if the returned stream is not valid JSON, the test fails.
  • Javascript: with this option, you execute your own custom JavaScript that analyzes the returned stream. Any assertion failure returned by your script makes the test fail.
  • Max Response Time (ms): if the response time exceeds the limit you enter, the API test is considered to have failed.

The Acme API Monitors World Bank Countries API monitor specifically requests the API’s country information for Brazil. It uses the default World Bank Countries API format, which is XML. A typical correct response looks like this:

WorldBankCountryXML

If we want to know that, not only was text successfully returned by this API monitor, but the information returned was actually the information about Brazil, we could use the Regex validations option to search for:

wb:country id="BRA"

in the returned XML. Here’s how we do this:

world-bank-countries-validate-brazil

Clicking “Test Now” produces a successful result when the World Bank Countries API is functioning properly.

But, if we ask our Regex validation to search for:

wb:country id="qqq"

and click “Test Now” we get this result:

invalid-regex-response

The call to the API succeeded with respect to the API returning a response, but the criterion we specified for considering the response valid (the text had to include wb:country id="qqq") was not satisfied, so the Validation failed (as should be the case, since our monitor’s GET URL is for Brazil, not for country “qqq”…).

This test illustrates how you can utilize the API Science API monitor settings to effectively customize API test settings to conform to the requirements needed to effectively serve your customers.

The “Pre-Process Script” section provides additional capability. You can embed JavaScript that is key to your normal operations into your API tests before you call an API (internal or external), as another measure of configuring a test that realistically replicates your normal business functioning.