API Check Commands, Variables and Validators

API Check Steps are broken down into three categories: Commands, Variables, and Validators. Commands (color-coded blue) act as tasks to complete or (more broadly) steps for your API Check; Variables (color-coded purple) set a variable from a response that can be used in a subsequent step; Validations (color-coded green) verify elements that should be present before registering a failure.  

Table of Contents:

Commands, Variables and Validators in a Nutshell

Commands

Variables

Validations

Commands, Variables and Validators At A Glance

  • Add authentication settings and GET, POST, PUT, and other commands to tell your endpoints what to do.

  • Set a variable from a response that can be used in a subsequent step.

  • Validate, or confirm, if the command you’ve used in a previous step was successful.

Commands

Return

mceclip0.png

Here are the commands used in an API check. 

Authentication & Settings

Return

Set HTTP Basic Auth User and Password, designate Content-Type, and adjust settings for the check. Settings include:

 

  • Certificate: PEM encoded client certificate to be used for mTLS authentication.
  • Key: PEM encoded client certificate key to be used for mTLS authentication.
  • Passphrase: Optional passphrase for the client certificate key.
  • Follow Redirects? - Determine when the check will follow Redirects. This option is off by default.
  • Ignore SSL/TLS Verification Errors? - Ignore errors such as expired SSL certificates or incorrect TLS configuration. This option may be useful when using self-signed certificates.

 

GET URL

Return

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

Return

Send data to a URL using HTTP POST.

PUT to URL 

Return

Send data to a URL using HTTP PUT.

PATCH to URL

Return

Send data to a URL using HTTP PATCH.

DELETE URL

Return

Load a URL using HTTP DELETE.

Variables

Return

mceclip1.png

Set a variable from the response that can be used in a subsequent step. 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>

Set Variable name from current date and time

Return

Name your variable, then specify a timezone location, any offset from that location’s timezone (specified in seconds), and the time format. For example, if you wanted to use a timestamp from 3 minutes ago you would use -180, or simply 180 for a timestamp 3 minutes into the future. To render the date (year and month) and time, use a format like the following:

%Y-%m-%d %H:%M:%S. 

Set variable name to a random value from a list

Return

Name your variable, then list any variants that should be included in a comma separated list of values. For example, to have a check that will randomly assign values aaa, bbb, or ccc, list the variants as follows:

 aaa,bbb,ccc 

Please note: previously defined variables can also be listed as variants, and their value will be interpolated in subsequent steps. See second example below:

$variable1$,$variable2$

You can use this type of variable to check that a response contains one of multiple possible unique values. There are a number of use cases for this action, such as appending a random value from the list to a string or verifying the response was properly received.  

Set variable name to a random value from a range

Return

Name your variable, then list the left and right margins for a range. The value assigned to the variable will come from this range of numbers, including the leftmost or rightmost margin of the range. A range from 0 to 100 will include 0, 100, and each possible number in between those two margins.

Set variable name to a literal value

Return

Name your variable, then define a value. Variables can be called within other steps, including other variables, to form complex strings. For example, you can define one literal value (CONST1) and then assign it as part of another constant literal value (CONST2). Using this technique, you can send a token like:

CONST1 = MYTOKENVALUE

CONST2 = “Authorization: Bearer $CONST1$” 

Set variable name from response body or response header

Return

Name your variable, then define the selector that contains the response you need. For example:

authorization.token[0]

This variable type can use regular expressions, matched fully or as a submatch from a larger group (useful for overly lengthy responses). This variable type allows regex. 

Validations

Return

mceclip2.png

Here are validators you can use in an API check. 

HTTP Status Code Should Be Status

Return

Check that the HTTP status code matches the specified status (eg. 200 or 404).

HTTP Status Code Indicates Success

Return

Check that the HTTP status code indicates success (200-299).

HTTP Header Should/Should Not Contain Text/Regex

Return

Check that the HTTP header matches or does not match the specified text or regex. 

For example, to retrieve a header Server from this endpoint, we format as follows:

header-matches-value.png

We can also use regex for complex string matching, such as this example looking for a 56 character alphanumeric string that also contains punctuation:

header-matches-regex.png

Response Should/Should Not Contain Text

Return

Check that the response contains or does not contain the given text.

Response Should/Should Not Match Regex

Return

Check that the response matches or does not match the given regex.

Selector Value from Response Does/Does Not Match Value

Return

Check that the selected value in the response does or does not match the given value. Note: it is possible to use variables set previously as a form of validation. 

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/Does Not Match Regex

Return

Check that the selected value in the response does or 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

Return

Check that a numeric value from the response is equal to/greater than/etc. a value or variable.

Numeric-Selector.gif

Response Protocol is Value

Return

Check that the response matches the expected protocol. Use this option to monitor your endpoint TLS configuration and prevent your visitors seeing a warning if TLS fails. Possible options include:

  • HTTP/2.0
  • HTTP/1.1
  • HTTP/1.0

protocol_is.png

Uses standard system Certificate Authorities for verification purposes. This validator does not check expiry date, only the current TLS configuration. 

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

Comments

0 comments

Article is closed for comments.

Have more questions?
Submit a request
Share it, if you like it.