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 in intervals ranging from 5 to 60 minutes. This tutorial assumes you’ve already logged into Uptime.com.
- Adding Your First API Check
- Use Case Example
- Failed Checks
- Root Cause Analysis
- Finalizing Your API Check
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.
Password Masking
Uptime.com includes password masking for passwords used in API checks. Ordinarily, Uptime.com identifies a password field and automatically obscures the text.
In some cases, Uptime.com is not able to detect the field is a password field and will not mask its entries. In these cases, you can use the following example as a guide to create a password element Uptime.com will detect:
Non-detected password element:
div.foo > input[name=testpassword]
Adjust to:
body:not([data-pw]) div.foo > input[name=testpassword]
Access Tokens
Uptime.com API checks can request an access token your server can issue for multiple sessions. Access tokens identify and authorize Uptime.com to fetch or query API resources without the need to authenticate the user and password, which can present a security risk.
To collect the token, create a command for Set Variable Name from Response Body.
Use the following formats to specify a selector:
For JSON responses: JSONPath or dot format, e.g. result.tokens[0].access_token
For XML responses: XPath, e.g. /result/token[1]/@access_token
Access tokens can be used in any subsequent step (in HTTP headers or data) using the validator Selector Value from Response Matches Value. Simply enclose the variable name in dollar signs ($), as in this example:
HTTP Header: Authorization: Bearer $TOKEN$
JSON Data: {"authtoken": "$TOKEN$"}
XML Data: <authtoken>$TOKEN$</authtoken>
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.
- GET https://httpbin.org/status/200
- Validate status code is 200
- GET https://httpbin.org/get?test=1
- Validate status code is 200
- Validate response contains `{"test":"1"}`
- POST https://httpbin.org/post with URLencoded data “test=1&other=2”
- Validate status code 200
- Validate response contains {"other":"2","test":"1"}
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
When a probe server detects downtime, or fails to register as UP, the API Check you've configured will attempt a retry based on the number of retry attempts you've configured for this check. Please note: The retry intervals for API checks are two minutes, as opposed to one minute for other 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.
Root Cause Analysis
API checks have a root cause analysis tool to identify the specific step where failure occurred, and identify the problem. This information is included in the alert email issued to your check contacts.
The Root cause analysis screen provides detailed check results, including response time metrics for each step the check was able to complete prior to failure.
Sample Failed Check
The person who created this failed check forgot to POST with the correct URL encoded data. The data that was returned was completely different and the result was an alert issued.
Finalizing Your API Check
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.