API Check Basics

This article will cover the creation of an API Check and its purpose within the Uptime ecosystem. An API check will monitor API using multiple HTTP(S) requests. This tutorial assumes you’ve already logged into Uptime.com.

Adding Your First API Check

To access an API Check, click on Monitoring in the left-hand menu, then Checks, followed by Add New. Select API from the Check Type drop-down menu.

APIs are useful for many Web applications.

REST API is an architectural styling that allows access to server resources. It’s the basis for many applications that exchange data online. REST API principles are helpful when you’re trying to automate data flow, query for resources, or, in our case, verify uptime.

To apply the principles within this tutorial to your server, you would need to write your requests in a language that your server can understand.

The following use case uses httpbin.org to illustrate a basic example with common commands. You may want to review our Field Explanation support article for more detailed definitions of terms you’re likely to encounter.  

Use Case - Query HTTPBin Utilizing REST API

REST API is a method of querying a server for resources, and we can see the status of a query conveyed in HTTP status codes. Uptime.com can use REST API to verify not only that a query was successful, but the data itself using specific values we ask it to retrieve.

A simple API request like this one, utilizing a mix of GET and POST requests, helps to verify a server is responding and ready to accept commands. This example will query from multiple locations and only alert the specified contacts if the time to response exceeds 30 seconds. This allowance will give the server enough time to process our request during even the most high-traffic periods of use, while avoiding false positives that waste time to clear.

We will need eight commands to finalize our check.   

  1. GET https://httpbin.org/status/200
  2. Validate status code is 200
  3. GET https://httpbin.org/get?test=1
  4. Validate status code is 200
  5. Validate response contains `{"test":"1"}`
  6. POST https://httpbin.org/post with URLencoded data “test=1&other=2”
  7. Validate status code 200
  8. Validate response contains {"other":"2","test":"1"}

API-check.png

Note that we can control how frequently a check is run, as well as any escalations. We may decide, based on maintenance or total downtime, that partial downtime is acceptable under certain conditions.

We can also download the HTML of the returned data, or review it inline by clicking the small blue “i” to load details.

Failed Checks

Using the returned data, debugging our requests is much easier. We never need to leave the page to see what Uptime.com sees when it makes the request. We can check for inconsistencies in our code, or review the returned data manually for other reasons.

We can access this data by returning to our check screen.

503-returned.png

Our status code is not consistent with what we expect. In this case, the test will query again until it gets the status code it wants, or 30 seconds pass. No need to raise the alarm yet, but it’s good to get some specifics on the error in question.

failed-API-check.png

If there was a problem with syntax returned, creating more significant downtime, we might use these details to review the response within the header or body of the page.

header-body.png

The person who created this failed check forgot to POST with URL encoded data. The data returned was completely different as a result. A more experienced user would correct the query with the proper syntax, test, and then finalize.

Once finalized, the test should deploy with no further issues or need for input on our end.

Finalizing Your Use Case

REST-API.png

Before we can deploy an API use case, it’s helpful to verify the test is working. There is a combination of GET and POST steps, with accompanying validations, which constitute a finalized test. Every test is different.

The best guidance we can provide in finalizing an API Check is to debug it, review the data it returns, and be sure you are getting the anticipated responses from your server in the syntax you expect. Debugging and verifying prevents false positives, and makes your API Check as useful as possible.

It’s helpful to familiarize yourself with our Field Explanation support article for a more detailed breakdown of the terminology you might encounter using the tool.