How to Create an Automated Custom Web Site that Displays API Uptime Data

Previous posts described how to use curl, cron, JSON, Python, matplotlib, and HTML to create an automatically-updated custom API performance web page.

In addition to providing API performance data, the API Science API also provides uptime data for the APIs you monitor. In this post, I’ll demonstrate how to download API uptime data and create a web page that consists of a pie chart depicting the API’s uptime over a particular time frame.

Getting the Data using curl

The post How to Use cron and curl to Regularly Download API Performance Data illustrates how to download API monitor data using curl. The curl code accesses API Science’s Performance API to download the performance data for a specified API monitor over a specified time period. The curl code for downloading uptime data is similar:

curl ‘https://api.apiscience.com/v1/monitors/1572753/performance.json?preset=lastWeek&resolution=hour’ -H ‘Authorization: Bearer xyzq…’

Here, the numeric 1572753 is the identity of the particular monitor for which you’re seeking performance data. preset=lastWeek means we’re accessing the monitor data for the past week. resolution=hour states that we want the monitor data binned by hour. The Bearer variable is your authorization code for accessing the API Science API.

This curl command is embedded into a command script that outputs the received JSON data to a text file that can be read by Python. The uptime JSON data consists of a heading like this:

"meta":{"status":"success","numberOfResults":168,"resolution":"hour","startPeriod":"2019-01-12T00:40:44.759Z","endPeriod":"2019-01-19T00:40:40.676Z"}

followed by data packets like this:

"meta":{"status":"success","numberOfResults":168,"resolution":"hour","startPeriod":"2019-01-12T00:40:44.759Z","endPeriod":"2019-01-19T00:40:40.676Z"}

Reading the JSON Data into Python

The strategy in the post How to Use Python to Extract JSON API Performance Data can be easily adapted to extract the downloaded JSON Uptime data. We simply have the Python program open the JSON file and load the data into a Python dictionary (named uptime in this case):

import json

with open('uptime.json') as f:
    uptime = json.load(f)

Using Matplotlib to Make an Uptime Pie Chart

The post How to Use MatPlotLib to Display API Performance Data describes how to make a Matplotlib XY plot with time on the x-axis and performance on the y-axis. In this example, we use Matplotlib to create a pie chart that maps uptime versus downtime.

Having loaded the JSON uptime data into Python, we sum all the uptime values, then divide by the total number of results, thus computing the average uptime over the tested time frame:

total_uptime_pct = 0.
for i in range(n_results):
    total_uptime_pct += uptime['data'][i]['uptime']

up_percent = total_uptime_pct / n_results
down_percent = 100. - up_percent

The downtime percent is simply 100.% minus the uptime average.

The Python statements that create the pie chart (adapted from this example) are:

labels = 'Up', 'Down'
sizes = [up_percent, down_percent]
fig1, ax1 = plt.subplots()
ax1.pie(sizes, labels=labels, autopct='%1.1f%%', startangle=90)
ax1.axis('equal')

title = '[' + uptime['meta']['startPeriod'] + ' through ' + uptime['meta']['endPeriod'] + ']'
plt.title(title)

plt.savefig('/home/kevin/APIScience/custom_reports/1572753_uptime_past_week.png')

The last line outputs the plot to a PNG file that can be loaded into an HTML web page.

Here’s an example plot:

Staying Up to Date Using cron and HTML’s “refresh” Meta Parameter

cron is a job scheduler that runs on Linux and Mac (Windows and most other operating systems have equivalents). cron can be used to launch a script that runs the curl command to download the latest uptime data and port it to a text file. Subsequently, the Python program is run to read in the new uptime file and create a new pie chart containing the latest uptime data.

A simple HTML file displays the latest pie chart:

<html>
<head>
<title>Monitor 1572753 (Dog and Meal Status) API Uptime</title>
<meta http-equiv="refresh" content="60">
</head>
<body>
<h3>Monitor 1572753 (Dog and Meal Status) API Uptime</h3>
<img src="1572753_uptime_past_week.png"</img>
</body>
</html>

Note the meta line. This tells the browser to refresh this page every 60 seconds. Thus, if the cron command re-launches while the user is viewing the page, the web page will be automatically updated with the latest pie chart within 60 seconds, without any user action.

Conclusion

With a very small amount of code, we’ve applied scripts, curl, JSON, Python, Matplotlib, cron, and HTML to create an automatically-updated web page that displays API uptime metrics based on data accessed from the API Science API.

–Kevin Farnham