API Check Use Cases and Examples

This document outlines some full and partial use cases illustrating various methods the API check can utilize to monitor endpoints. For API Check setup instructions, see this article.

Table of Contents

• Checking Multiple API Endpoints, and Using Variables
• Check for Integration Errors
• Form Submission
• Handling File Downloads & Uploads
• OAuth with the API Check
• Using Variables with an API Check
  • How Variables Work
• Connecting to Insecure Endpoints

Checking Multiple API Endpoints, and Using Variables

Return

Uptime.com can monitor an API to verify not only that a query was successful, but the data itself using specific values it retrieved. We will use this operation to query multiple endpoints with the same variable.

We will use 8 steps including both commands and validators to finalize our check.  

1. GET https://httpbin.org/json

2. Validate HTTP status code is 200

3. Set a variable named “title” and use the first value from the response body

4. POST the value stored in variable $title$ to HTTPbin (note we surround our variable with ‘$’)

5. Check that the response contains the value we defined

6. A secondary validator used for more precision

7. POST our variable to a new URL (httpbin.org/anything)

8. Check that the response contains the text we defined

We check three endpoints and use a number of validators that help define specific responses we are looking for. We can change these variables according to our needs. 

If we wanted to test the Uptime.com REST API, for instance, we could set our variable to be a check’s service number. Then we could query multiple check related endpoints with this service number for a specific response. 

Check for Integration Errors

Return

You can utilize an API check and a user account with read-only permissions to create a simple check that will notify any administrator if an integration fails and is paused (although Uptime.com does send an email notification to all Administrators when this happens).

1. Create a read-only user for your Uptime.com account
2. Log in as this user and retrieve that user’s API key from Settings > API
3. Create a new API check 
4. Use a GET step to monitor https://uptime.com/api/v1/integrations/?is_errored=true
5. Add a validation step that validates the select “count” has a value that matches “0”

This check will fail when is_errored reports when one integration has failed. Below is an alternative to the above use case, using the Numeric Selector matches Value validator:

Use this technique if, for example, you need to know that more than one integration is failing.

Form Submission

Return

This example will utilize HTTPbin to pass data as a form field. The “anything” endpoint will return whatever we send to it, so we can set the Content-Type field, to be multipart/form-data, and the input data to send with the request, within the Form box.

 

We’ve highlighted the relevant portion of the response from HTTPbin below:

 

 

You can also use a PATCH request, to update the values inputted in the previous POST request Form box.

 

We can then use a Validator step to validate the data was submitted and the response contains the given text.

 

Handling File Downloads & Uploads

Return

In the example below, we will be showing how to use the API check to send files with the POST, PUT, and PATCH requests. By setting the Content-Type to multipart/form-data, the Files option will appear.

Enter the URL of the file in the Files field with the following syntax:

file: http://www.url.com/file.ext:

 

POST Method

 

 

PUT Method

PATCH Method

 

OAuth with the API Check

Return

This example will show how to retrieve an oAuth token for use in your API check. To achieve our end goal, we will need to POST data to a specific URL containing some parameters required for authentication. We can do all of this in a single step with a POST Command:

POST to https://myURL.com/oauth/token 

This POST request can contain Content Type, Data, and HTTP Headers if required. Here, we have chosen to designate the content-type application/x-www-form-urlencoded

The Data field will contain the client’s ID and any requisite tokens or authorization required to authenticate:

Data:  grant_type=client_credentials&client_id=client_id&client_secret=client_token

No headers are needed for this operation. 

Test this operation to be sure authentication is successful. Upon a successful test, you are ready to proceed utilizing endpoints that require user authentication. As a general rule, Uptime.com recommends your authenticated test user has minimal permissions.

Using Variables with an API Check

Return

There are a number of variable types you can utilize with an API check, and this demo use cases will help to familiarize yourself with how they work. We’ll use httpbin for this example, as it’s easy to examine response and control our variables for a test case. 

First, we’ll create a GET URL step that looks for httpbin and ensures its status is 200 OK. Steps 3-9 are where we declare our variables, and step 10 is where we post the data we want to examine. 

The POST step 10 is where we use our variables. This step encloses each variable in $, such as $ORIGIN$ or $CONST$ before it can be used.

To learn more about variable types, see our section in API Check commands and validators. To verify the data was sent, we’ll need to click the , which will give us output as follows:

How Variables Work

Return

Variables are dependent on the type you want, and syntax is important in some variable types. For example, you will need to utilize date/time format (%Y-%m-%d %H:%M:%S will output a value like 2022-07-26 20:36:15) when you want to set a variable with the current date and time. 

A variable from the response, either the header or body, must be declared after the response is received. As an example, it would not be possible to declare a variable for selector.one on myurl.com without first using a GET or POST step to visit myurl.com. However, some variable types such as a variable from a range or list can be declared ahead of visiting a URL. This is useful when you need a literal value representing something, such as a token or test phrase.

Connecting to Insecure Endpoints

Return

It is common for testing/staging environments to have self-signed certificates or otherwise insecure TLS protocols. Here we will be talking about what you can do to bypass any insecure endpoints that you may still require monitoring.

By default, Uptime.com’s API Check expects a secure connection. However, we understand that this will not always be the case.

As an example, using badssl.com, we can see that using a self-signed certificate causes the API check to return an error. The same can be seen if any other HTTP method Is used.

The Ignore SSL/TLS verification errors checkbox in the Authentication & Settings step for the API check offers a workaround. This will ignore any of the SSL/TLS warnings that you would normally get when using a self-signed or otherwise insecure certificate.