The response of an API request can be checked for correctness and timeliness by using assertions on the response data. Assertions are flexible statements that combine preset modifiers with custom values to meet the needs of a broad set of use cases.
How assertions work
Assertions are statements you create that check one aspect of the HTTP response. You can create multiple assertions for one check that assert various aspects of a response, for example:
- HTTP response status equals 200.
- HTTP response body equals the text “success”.
- HTTP response time is lower than 2000 milliseconds.
- HTTP response header “X-Custom-Header” equals “SomeValue”.
- HTTP response JSON object has a key called “accountBalance” with a value greater than 9999
In each assertion, a source is connected to a comparison and a target.
In some cases a property is added, for example when asserting headers or JSON response bodies.
Assertions are executed from top to bottom. If one assertion fails, the full check is considered as failed.
On each API check assertion, the following sources are available:
The HTTP response status, parsed as an integer.
The response body parsed as a JSON object. This allows inspection of the JSON object using the “Has key” and “Has value” comparisons.
The response body parsed as a JSON array. With JSON arrays, you get the option to target the last, first or any nth item and then apply the same comparison as a JSON object. Very handy when your API endpoint returns collections.
The response body as plain text.
The response headers as an array of key/value pairs. This allows the inspection of headers using the “property” field to match the header name and the “target” field to match the header value.
The response time of the full API request in milliseconds, parsed as an integer value.
The property field is a free form text field, mostly used to identify the name of a header or the key of a JSON object to be used in the assertion statement.
When used on JSON bodies, the property field accepts nested identifiers in the form of dot-separated strings to target nested properties in an object, i.e.
Read more about asserting JSON response bodies below.
Comparisons are the operators that work on the source data and target data, i.e.
response time (source) is LESS THAN 150 (target) or
status code EQUALS 200. You get it.
On each API check assertion, the following comparisons are available:
- Equals / Not equals
- Is empty / Not empty
- Has key / Not has key
- Has value / Not has value
- Greater than
- Less than
The target field is a free form text field that determines the desired outcome of your assertion.
Asserting JSON responses
A big part of knowing your API is still working as designed is parsing and checking the response body. In many cases this will be a JSON formatted document returned from a REST API.
Asserting basic types
Asserting string, boolean and number values works exactly as you’d expect, e.g. the example below asserts the number value of
id property is greater than
You can traverse a JSON object using a dot notation. In the example below we are checking the string-based
property that is part of the
product object in the JSON response.
This next example checks for a boolean value in the
For response bodies with JSON arrays instead of objects you have the following options:
- Length: let’s check you checks the amount of items in the returned array.
- First item: picks the first item in the array.
- Last item: picks the last item in the array.
- Nth item: picks any item in the array by index.
In the first example below we check if the total array has more than 30 items using the Length and Greater than options.
In this example we pick the last item in the array and check if the
customerId property has the value
In the last example we pick the item with index value 4. This is the 5th item as array indexes start at 0. We then assert
responseTime property is less than
Last updated on February 4, 2019