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.
Checking Multiple API Endpoints, and Using Variables
Uptime.com can use API to verify not only that a query was successful, but the data itself using specific values we ask it to retrieve. 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 in ‘$’)
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
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.
- Create a read-only user for your Uptime.com account
- Log in as this user and retrieve that user’s API key from Settings>API
- Create a new API check
- Use a GET step to monitor https://uptime.com/api/v1/integrations/?is_errored=true
- Add a validation step that validate 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 1 integration is failing.
Form Submission
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 use a selector value to validate that the correct data was passed.
We’ve highlighted the relevant portion of the response from HTTPbin below:
We can use a validator step to validate the data was submitted and is present in the response body:
OAuth with the API Check
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
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
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.