API Assertions

Last modified on July 26, 2024

API endpoint monitors can use assertions to verify the response contents. Without assertions, the monitor only tests whether the endpoint is accessible via HTTP, but does not test the actual data returned by your API. If assertions are defined, the test is only considered successful if all of the assertions pass.

Each monitor step can have any number of assertions. Assertions are made against the response headers or body and can be simple substring checks, regular expression matches, as well as JSON- and XML-specific assertions.

Add assertions

You can add assertions both when you create a new API monitor and edit existing API monitors.

AlertSite UXM

The Assertions table is displayed next to the response. (If the response is not displayed, click Validate Step.)

The easiest way to add assertions is to do this directly from the response body: click a line in a JSON or XML response, or select a keyword or phrase in a text response, then click Add Keyword Assertion. You can also add the assertions manually to the table.

Assertions editor in AlertSite UXM

Click the image to enlarge it.

When you add XML assertions, AlertSite suggests possible assertions for the selected element and its attributes, and you can choose which ones to add.

API monitors: Adding XML assertions

Click the image to enlarge it.

To create an assertion for a response header, switch to the Headers tab, click the header in the list, then click Add Header Assertion. You can verify the header value or just the presence of a specific header in the response.

API monitors: Adding HTTP header assertions

Click the image to enlarge it.

AlertSite 1.0

You can view and edit assertions in the Assertions table on the monitor configuration screen. Click to add a new assertion and specify the assertion type, source data, and expected value.

Assertions editor in AlertSite 1.0

Click the image to enlarge it.

Assertion configuration

Each assertion consists of the following elements:

Column Description
Source

What is being verified:

  • Response - Raw Text – the entire text contents of the response body.

  • JSON Response – a specific field or fields in a JSON response.

  • XML Response – a specific node or attribute in an XML response.

    Note that XML assertions are not supported for HTML. This is because HTML is not necessarily valid for XML – for example, HTML can have unclosed tags (<img ...>, <br>) which is not allowed in XML.

  • Timeout – the maximum acceptable response time, in seconds, up to three decimal places. For example, 0.25. Steps without timeout assertions use the default timeout specified by the Step Timeout monitor option.

  • Status Code – the HTTP status code of the response. The status code is compared against a comma-separated list of valid or invalid status codes.

    By default, steps without status code assertions consider the following statuses successful:

  • Header – the presence or value of a specific HTTP response header.

    Note: Header assertions are not supported at locations running ReadyAPI 1.1.

Property

Specifies the JSON or XML field, or the HTTP response header to be verified.

  • JSON fields can be specified using JavaScript dot notation, for example, results[0].source. You can also use JSONPath expressions with complex filter conditions, such as $..book[?(@.price < 10)].title (the titles of all books cheaper than 10).

  • XML fields are specified using XPath, for example, //user[@id='12345']/name. AlertSite supports XPath 2.0.

  • HTTP header names are case-insensitive.

Operator

The comparison operator. Supported operators depend on the Source.

Response - Raw Text:

  • contains – verifies that the response contains the specified text (case-sensitive).

  • does not contain – verifies that the response does not contain the specified text (case-sensitive).

  • regular expression includes – verifies that the response contains a substring that matches the specified regular expression. See the notes below about the regular expression syntax.

  • regular expression excludes – verifies that the response does not contain a substring that matches the specified regular expression.

JSON Response or XML Response:

  • equals – verifies the value of the specified field, or the result of a JSONPath or XPath query. String comparisons are case-sensitive.

  • count – counts the number of occurrences of the specified field.

  • exists – verifies that the specified field exists (regardless of the value).

  • does not exist – verifies that the specified field does not exist.

  • regular expression includes – verifies that the field value contains a substring that matches the specified regular expression. See the notes below about the regular expression syntax.

  • regular expression excludes – verifies that the field value does not contain a substring that matches the specified regular expression.

Timeout:

  • less than or equal – verifies that the response time is less than or equals to the specified number of seconds.

Status Code:

  • equals – verifies that the response has a status code from the list. Use comma as a list separator: 200,201.

  • does not equal – verifies that the response status code is not one of the listed codes. Use comma as a list separator: 400,404,500.

Header:

  • equals – verifies that the response header has the specified value.

  • exists – verifies that the specified response header exists (regardless of the value).

  • regular expression includes – verifies that the response header contains a substring that matches the specified regular expression. See the notes below about the regular expression syntax.

Value

The expected value or the value to compare against. Depending on the assertion configuration, it can be a single value (such as text or number), a list of values, a JSON object or a regular expression. When AlertSite runs the assertion, it calculates the actual value of the specified Source and Property, and compares it to the value specified here.

Tips:

If you need more advanced checks (for example, verify header values or use scripts), you can convert your monitor to SoapUI and edit the generated SoapUI project.

JSONPath

JSON assertions can use JSONPath expressions to locate fields based on certain conditions or select multiple fields at once. See JSONPath Syntax for more information.

XPath

XML assertions use XPath to access elements in XML responses. AlertSite supports XPath 2.0. To learn more about the XPath syntax, please see this tutorial:

https://www.w3schools.com/xml/xpath_syntax.asp

or the formal specification:

http://www.w3.org/TR/xpath20/

Regular expressions

The regular expression syntax in API assertions is the one used in Java:

https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html#sum

Example

Match a timestamp in the yyyy-mm-ddThh:mm:ss.sssZ format:

\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z

Modifiers

Regular expressions can include modifiers to change the way the pattern matching is handled. The table below lists some common modifiers.

When a modifier appears at the beginning of the pattern, such as (?i)cat.*, it affects the whole pattern. If it appears mid-pattern, it only affects the portion of the pattern that follows.

To specify multiple modifiers, put them together as in (?ims).

Modifier Description
(?i) Enables case-insensitive matching. For example, (?i)cat.* matches cat, Cats, CATEGORY, and so on.

By default, only characters from the US-ASCII charset are being matched. To enable Unicode-aware case matching, use (?iu).

(?m) By default, ^ and $ match the beginning and end of the entire input. The (?m) modifier enables the multiline mode so that ^ and $ match the beginning and end of individual lines.
(?s) By default, . matches any character except for new line characters (\r and \n). If (?s) is used, . also matches new lines.
(?u) When used together with (?i), makes case-insensitive matching Unicode-aware.

See Also

JSONPath Syntax
Creating an API Endpoint Monitor
API Endpoint Monitor Settings

Highlight search results