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 in intervals ranging from 5 to 60 minutes. This tutorial assumes you’ve already logged into Uptime.com.

Table of Contents

Adding Your First API Check

Return

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 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

Return

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.  

api-use-case.png

  1. GET https://httpbin.org/json
  2. Validate status code is 200
  3. Set a variable “title” and use the first value from the response body
  4. POST the value stored in variable $title$ to HTTPbin

data.png

  1. Validate response contains ‘data’
  2. 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

Return

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

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.

failed-API-check.png

response-body.png

Root Cause Analysis

Return

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.

mceclip0.png

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

Return

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

Return

REST-API.pngBefore 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.

Was this article helpful?
0 out of 0 found this helpful