Evaluating API Monitor Checks Using the API Science API

Your API monitoring team can be alerted when an API that’s critical for your product goes down using API Science’s alerts capability, which provides the ability to notify your team about problems using email, a URL, Slack, PagerDuty, and HipChat. These methods can be extended using tools like IFTTT (IF This Then That) such that your monitor alerts can be broadcast to virtually any social media platform (for example, Todoist or Facebook).

While notifying your team when a critical situation arises, it is also possible to apply API Science’s own Application Programming Interface to develop custom tools that automate analysis of your monitor results. For example, the Checks component of the API allows you to request information about a monitor’s checks. The API reference describes checks as follows:

Checks represent a single run of your monitor. They contain detailed information about the actual API calls that took place.

A shell script that issues a curl command can be used to request information about monitor checks. For example:

curl 'https://api.apiscience.com/v1/monitors/1572022/checks.json'
    -H 'Authorization: Bearer MY_API_KEY'

Here, I’m requesting the checks information for my “br_Ireland” monitor, which queries the World Bank Countries API for information about Brazil, with the query running from a server located in Ireland. This is an HTTP GET request to the World Bank API endpoint:

http://api.worldbank.org/countries/br

“br” is the World Bank country code for Brazil.

Using the API Science Checks API, I can gather the results of checks for my br_Ireland monitor, and analyze them using my own custom software.

A query to the Checks API for a successful check for my br_Ireland monitor produces a JSON response that looks like this:

{
  "meta": {
    "status": "success",
    "numberOfResults": 1
  },
  "data": [
    {
      "id": 118234601,
      "href": "https://api.apiscience.com/v1/checks/118234601.json",
      "status": "success",
      "statistics": {
        "resolve": 140.09,
        "connect": 75.38,
        "processing": 85.44,
        "transfer": 0.13,
        "total": 301.04,
        "downloadSize": 680
      },
      "monitor": {
        "href": "https://api.apiscience.com/v1/monitors/1572022.json",
        "name": "br Ireland"
      },
      "calls": [
        {
          "id": 138054314,
          "template": {
            "id": 1324667,
            "href": "https://api.apiscience.com/v1/monitors/1572022/templates/1324667.json",
            "name": null
          },
          "statistics": {
            "resolve": 140.09,
            "connect": 75.38,
            "processing": 85.44,
            "transfer": 0.13,
            "total": 301.04,
            "downloadSize": 680
          },
          "request": {
            "verb": "GET",
            "url": "http://api.worldbank.org/countries/br",
            "headers": [

            ],
            "body": "",
            "params": [

            ]
          },
          "response": {
            "contentType": "text/xml; charset=UTF-8",
            "stausCode": 200,
            "headers": [
              {
                "Date": "Thu, 23 Mar 2017 21:33:03 GMT"
              },
              {
                "Content-Type": "text/xml; charset=UTF-8"
              },
              {
                "Content-Length": "680"
              },
              {
                "Connection": "keep-alive"
              },
              {
                "X-Powered-By": "ASP.NET"
              },
              {
                "Set-Cookie": "TS01fa65e4=01359ee976b447c7e9670af2f161386dbb4d4d96bbd953b4ce5bc82c29722819bbd9b2f38e; Path=/"
              },
              {
                "Server": "Apigee Router"
              }
            ],
            "body": "\r\n\r\n  \r\n    BR\r\n    Brazil\r\n    Latin America & Caribbean \r\n    Latin America & Caribbean (excluding high income)\r\n    Upper middle income\r\n    IBRD\r\n    Brasilia\r\n    -47.9292\r\n    -15.7801\r\n  \r\n"
          },
          "validationFailures": [

          ],
          "createdAt": "2017-03-23T21:33:03.000Z",
          "updatedAt": "2017-03-23T21:33:04.000Z"
        }
      ],
      "alerts": [

      ],
      "createdAt": "2017-03-23T21:33:04.000Z",
      "updatedAt": "2017-03-23T21:33:04.000Z"
    }
  ],
  "pagination": {
    "last": "https://api.apiscience.com/v1/monitors/1572022/checks.json?start=118234601&page=173&count=1",
    "next": "https://api.apiscience.com/v1/monitors/1572022/checks.json?start=118234601&page=2&count=1"
  }
}

Interpreting these Results

This is a lot of data relating to a single check performed by my br_Ireland monitor. Let’s take a look at what this is showing us. To do this, I’ll describe what the primary JSON data elements in this API response represent.

The “meta” section at the top shows that the request to the API Science Checks API was successful, and it produced one check result for my br_Ireland monitor.

The “data” section contains the information about this specific br_Ireland check. This includes summary details about the check, including the curl timing statistics and the status of the check. In this example, the check was successful.

The “monitor” section identifies which monitor my request interrogated (i.e., “br_Ireland”).

The subsequent “calls” section shows the details of the br_Ireland call that was made during this check. We see timing statistics, the HTTP “verb” (“GET”), the URL that was called, and any headers or body information included in the API call to the br_Ireland API.

The “response” subsection provides the details of what was returned by the request. The “body” section shows the data that was returned. In this example, the “validationFailures” field indicates that none of my API Science validations for this monitor failed. The “alerts” section shows that no alerts were sent out to my API monitoring team due to the results of this check.

Thus, the “calls” section presents all data that was sent to the World Bank API in this particular br_Ireland API check, along with the resultant response data.

With this data in hand, we can proceed with developing customized responses to events that occur in the APIs that are crucial for our own product.

In my next post, I’ll compare this API Science Checks API response that showed a successful check for my br_Ireland monitor with the result the Checks API returns for a failed br_Ireland monitor check.

–Kevin Farnham

Leave a Reply

Your email address will not be published. Required fields are marked *