How to Use Your API Science One-Month Free Trial (Part 2)

Part 1 of this series introduced the API Science platform and described the basics of how you can utilize your free one-month trial to monitor and evaluate the internal and external APIs that are critical for your platform to be fully functional.

Once you have signed up and reviewed what API Science offers, the sensible next steps are to create your own API Science API monitor and configure the monitor’s settings as suits your needs.

Creating Your First API Science Monitor

Your API Science free 30-day trial includes sample API monitors that enable you to immediately explore the capabilities the API Science platform provides. But if you’ve come to API Science, it’s probably because your work utilizes APIs (external or internal) and you recognize the need to know the uptime of these APIs and their performance statistics, since your product is accessed by your customers on a 24/7 basis. This information is precisely what you’ll receive when you create your own custom API Science API monitor.

On your API Dashboard, you’ll see an “Add Monitor” button on the right above your monitors list, for example:

AcmeMonitors_Dashboard

Clicking “Add Monitor” brings you to a page like this:

NewMonitor0

The World Bank has an API whereby a call can request and receive basic information about a country. For example, to receive the summary information about Brazil, you can point a web browser to: http://api.worldbank.org/countries/br. Doing this in your browser produces an XML result similar to this:

WorldBankCountryXMLTo create a monitor for this API, fill in the form on your “Add Monitor” page, for example:

world-bank-countries-monitor-form

Click the “Test Now” button to verify your new API monitor. The results of the test call will be displayed below the “Test Now” button:

world-bank-countries-monitor-test-callClick “Save Monitor” to initiate automated testing of the API call. You’ll be brought to your new monitor’s summary results page, which provides the results of recent checks on the API call, uptime history, and alert configuration options.

The new monitor will also be added to your API Dashboard:

acme-dashboard-wb-monitor

Working with API Science Monitor Settings

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.

–Kevin Farnham