To get started with assertions, we recommend reading the Multi-step API Response article for an overview of its core functions and key features.
This article explains how assertions work and how they help verify API responses and ensure expected behavior.
Assertions
Within a step, you’ll find the Response, where you can configure assertions.
Assertions are conditions used to help verify your API responses. You can use these to check whether your API request was successful, a particular content from the response exists, or if an unexpected behavior happens. You can easily define multiple validations to verify that your API responds correctly and returns the expected data.
In the example below, an assertion checks if the value of the product price is greater than 100. Assertions are defined using four fields: source, property, comparison, and target value.
Each field corresponds to a specific value to determine how the response should be evaluated. The availability of these fields may vary depending on the response check.
Below are the assertion fields that you can define based on your monitoring requirements.
Assertion source
This field lets you define the origin or the data source that you want to check. This could be from a Response body as JSON, Response body as text, or an attribute from an HTTP response, such as Status code and many more. For more information, refer to
Assertion sources.
Assertion property
Some
assertion sources like Response body as JSON or Response header require you to specify a particular content check to further validate the response. If you want to check specific data from the response, you need to provide the exact property value that matches the assertion source type. In the example above, the Products[0].Price is the property value.
Assertion comparison
This field lets you select the comparator used to evaluate the relationship to the assertion target value. By default, it is set to Is equal to, but you can select other
comparison options based on your requirements.
Assertion target value
Suppose you want to compare the product price retrieved from the API response to a specific value, such as 10. In this case, the 10 is the assertion target value that you want to compare against.
This field lets you define a value to use as the basis for comparison. Depending on the selected assertion source, property, and comparison type, this value can be text, a number, or a boolean. You can also use a variable reference that represents any of these value types.
What happens if an assertion condition is not met?
All assertions in a step are executed as soon as the HTTP request has been completed and the response has been processed. As a rule, each assertion is evaluated independently, even if a previous assertion fails. As a result, it is possible that multiple assertion failures are reported for a single step.
If any assertion fails, the monitor stops executing immediately. Any subsequent steps are skipped, and the monitor check reports an error. The error code and description depend on the type of failure. If multiple assertions fail, the first failure in the list is treated as the most important one. If you want your monitor to continue running all steps even if a failure occurs, refer to the Error handling in Multi-step APIs article.
In some cases, it may be necessary to retry an assertion, for example, when a timing issue could cause a false negative. You can configure the assertion to be evaluated multiple times. For more information, refer to the Enabling the maximum number of attempts article.