API Check Basics

The API Check is a multi-step advanced check type that is intended to monitor API such as REST or SOAP. It can monitor from each probe server location in intervals ranging from 1 minute to 1 hour.

Please Note: Depending on your Subscription, the minimum check interval time may differ.

If you are looking for API check use cases, see this document. You can find more details on API Check commands and validation steps here. 

To skip to a specific section of the "API Check Basics" video, click the links with the !

Table of Contents

• API Checks At A Glance
• What Can the API Check Do?
• Adding Your First API Check
  • Password Masking
  • Access Tokens
• Testing Checks
  • Root Cause Analysis
• Finalizing Your API Check
• Use Cases and Examples

API Checks At A Glance

• Utilize POST, PUT, GET, PATCH & DELETE requests for your endpoints.

• Check the uptime of multiple URLs with GET requests.

• Use Root Cause Analysis to diagnose any check failures.

What Can the API Check Do?

Return to Top

1. Use a variety of POST, GET, PUT, PATCH & DELETE requests to deliver data to an endpoint, set a variable based on the response, and use that variable in subsequent requests
2. Use HTTP Headers to pass tokens for complex multi-step actions
3. Verify a specific status code or response for multiple endpoints
4. Utilize oAuth
5. Check the uptime of multiple URLs with GET requests

See API check use cases in this document.

Adding Your First API Check

Return

Skip to 0:13

• Click on Monitoring and then Checks, followed by Add New. 

• Select API from the Check Type dropdown menu. 

• Name your check, set the API Check’s interval. Next, assign any contacts that will receive alerts.
• The API Check has a global timeout threshold of 30 seconds by default, with a maximum value of 60 seconds. Set these thresholds in the Advanced tab. 

Please note: API checks do not support self-signed certificates. API checks will follow redirects, but will ignore status codes (such as 302).

Password Masking

Return

Uptime.com ordinarily identifies a password field and automatically obscures the text. If Uptime.com is not able to detect the password field, use the following example 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

Return

Uptime.com API checks can utilize an access token for multi-step operations. To collect the token, create a command to Set a Variable from response body/header depending on where the token is issued.

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

Use Access tokens 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>

 

Find more details on API Check variables here. 

Testing Checks

Return

• Click the Run Test button, which will run the check from our test server. Each step that passes will be colored green, while failed steps will be colored red.  

• 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. When a designated selector’s value does not match the response, you can use the i icon to view the value Uptime.com received. 

• The check will retry its operation depending on the Sensitivity value you have defined before it goes down. 
• Request Details will contain more detail. Click the “i” icon to view the response headers and body. The "Response Body" section can contain up to 8KB characters, to help you review and diagnose the full context of each step.

• If Run Test passes, and you have completed all the steps you intend your check to take, you are ready to click Save and deploy the check. 

Root Cause Analysis

Return

• API checks have a root cause analysis tool to diagnose check failure. A link to the check’s root cause analysis 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.

Finalizing Your Check

Return

To sum up:

• API Checks consist of GET and POST steps, with accompanying validations. Every check is different based on the needs of your test.
• Before you deploy, test with the Run Test button to verify your settings are returning the expected results. 
• Use the i icon to view Request Details to verify the response is intended. 

Tip: Add a step that will always fail at the end of your check to review check details. Remove this step when you are ready to deploy. 

Is this your first API check? We recommend using httpbin.org as a testing tool. 

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.

Note: the API check truncation limit is 256 KiB.

Use Cases and Examples

Return

For more information on scenarios in which an API check may be useful, please see our API Check Use Cases and Examples documentation.

You may use our Secure Vault to securely store your details. For more information review our support doc.

Want to see our checks in action? Check out our YouTube Library for more!