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 3 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
- Commands and Validators
- 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.
Please note: API checks do not support self-signed certificates.
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
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.
This simple API request will demonstrate how to use data from a query to validate the response with a mix of GET and POST requests the API Check provides. This use case will show how to set, validate, and use variables to verify a server is responding properly.
This example will query from multiple locations and only alert the specified contacts if the time to response exceeds 30 seconds. This 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 use 6 commands and validators to finalize our check.
- GET https://httpbin.org/json
- Validate status code is 200
- Set a variable “title” and use the first value from the response body
- POST the value stored in variable $title$ to HTTPbin
- Validate response contains ‘data’
- Parse the response and validate that data retrieved with selector ‘data’ matches the variable $title$
We can also view the returned data 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.
Uptime.com will show the specific reason a step has failed, as depicted above where the status code is not consistent with what was requested.
The check will retry depending on the Sensitivity value you have defined.
If there was a problem with syntax returned, we could view the response within the test screen.
Root Cause Analysis
API checks have a root cause analysis tool to identify the specific step where the 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.
Commands and Validators
Steps are broken down into two categories: Commands and Validations. Commands (color-coded blue) act as tasks to complete or (more broadly) steps for your API Check, Validations (color-coded green) verify elements that should be present before registering a failure.
Commands
Here are the commands used in an API check.
GET URL
Load a URL using HTTP GET.Using this step, an API check can be used as an advanced HTTP check, where you GET URL in one step, then Validate with HTTP Status Code Indicates Success. Repeat as often as needed.
POST to URL
Send data to a URL using HTTP POST.
PUT to URL
Send data to a URL using HTTP PUT.
PATCH to URL
Send data to a URL using HTTP PATCH.
DELETE URL
Load a URL using HTTP DELETE.
Set a Variable Name from Selector Selector
Set a variable from the response that can be used in a subsequent step.
Use the following formats to specify 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
To use a variable in any subsequent step (in HTTP headers or data), enclose the variable name in dollar signs ($), for example:
HTTP Header: Authorization: Bearer $TOKEN$
JSON Data: {"authtoken": "$TOKEN$"}
XML Data: <authtoken>$TOKEN$</authtoken>
Validators
Here are validators you can use in an API check.
HTTP Status Code Should Be Status
Check that the HTTP status code matches the specified status (eg. 200 or 404).
HTTP Status Code Indicates Success
Check that the HTTP status code indicates success (200-299).
Response Should Contain Text
Check that the response contains the given text.
Response Should Not Contain Text
Check that the response does not contain the given text.
Response Should Match Regex
Check that the response matches the given regex.
Response Should Not Match Regex
Check that the response does not match the given regex.
Selector Value from Response Matches Value
Check that the selected value in the response matches the given value.
Use the following formats to specify 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
Selector Value from Response Does Not Match Value
Check that the selected value in the response does not match the given value.
Use the following formats to specify 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
Selector Value from Response Matches Regex
Check that the selected value in the response matches the given regex.
Use the following formats to specify 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
Selector Value from Response Does Not Match Regex
Check that the selected value in the response does not match the given regex.
Use the following formats to specify 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
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.