This article will cover the creation of an API Check and its purpose within the Uptime ecosystem. An API check will monitor API (such as SOAP or REST) using multiple HTTP(S) requests in intervals ranging from 3 to 60 minutes. This tutorial assumes you’ve already logged into Uptime.com.
If you are looking for API check use cases, see this document.
- Adding Your First API Check
- 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.
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>
Failed Checks
Using the returned data, debugging our requests is much easier. Click the green Run Test button and you never need to leave the check edit screeen 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
Numeric Value Selector Condition Value
Check that a numeric value from the response is equal to/greater than/etc. a value or variable.
Numeric Value Selector Condition Value
Check that a numeric value from the response is equal to/greater than/etc. a value or variable.
Finalizing Your API Check
Before we can deploy an API use case, it’s helpful to verify the test is working. Utilize the Run Test button to verify your settings are returning the expected results. To run a test, select from any of the probe server locations available to your account from the Location dropdown and click Run Test.
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.