Supported assertions and syntax
API Studio provides a range of assertions to validate various aspects of API responses, ensuring accuracy and compliance with expected outcomes. These assertions are classified into two main categories:
- Response metadata validation. Validates general response attributes such as status codes, headers, response status, and response time.
- Response payload validation. Focuses on verifying the content and structure of the response body, including JSON, XML, and plain text content.
Each assertion type includes supported actions and sample configurations, making it easier to define precise validation checks and confirm the reliability of the API.
Response metadata validation
This category encompasses validations for various general metadata returned with the API response. It ensures that essential response attributes, such as status codes, headers, and response time, align with expected values. These validations help confirm that the API is functioning correctly at a high level and meeting basic performance and communication standards. The following aspects are covered under metadata validation:
- Status code
-
Validates HTTP response codes like 200, 404, and 500, to ensure that the API responds with the correct status indicating the success or failure of the request.
Supported actions
equals
notEquals
lessThan
greaterThan
Example
name: "Validate the response code" key: code value: 201 action: equals
This assertion checks if the HTTP response code is
201
, which indicates that a resource was successfully created. It passes if the response code matches201
; otherwise, it fails. - Response time
-
Measures how quickly the API responded, in milliseconds, ensuring the performance meets the required speed benchmarks.
Supported actions
equals
notEquals
lessThan
greaterThan
Example
name: "Validate the response time" key: responseTime value: 2000 action: lessThan
This assertion checks if the response time is less than
2000
milliseconds. It passes if the actual response time is shorter than2000
; otherwise, it fails. - Response status
-
Verifies the presence and accuracy of status indicators such as OK, FAILED, or ERROR, which provide a quick understanding of the overall request outcome.
Supported actions
equals
notEquals
include
lengthOf
Example
name: "Validate the response status" key: status value: OK action: equals
This assertion checks if the response status is
OK
. It passes if the actual status matchesOK
; otherwise, it fails. - Response headers
-
Validates the presence and correct values of essential HTTP headers, including Content-Type and Cache-Control, which define the format and behavior of the response.
Supported actions
equals
notEquals
haveProperty
notHaveProperty
include
lengthOf
Example
name: "Validate the header content type with value" key: header().Content-Type value: application/json action: include
This assertion checks if the
Content-Type
header in the response includes the valueapplication/json
. It passes if the header contains this value; otherwise, it fails.
Response payload validation
This category focuses on validations that inspect and verify the content within the body of the API response. It ensures that the actual data returned matches the expected structure, values, and format. By validating the response payload, it is possible to confirm that the API not only performs correctly but also returns accurate and meaningful data in the desired format. The following aspects are covered under payload validation:
- JSON content
-
Validates the values, structure, arrays, and object properties within the JSON response, ensuring that the returned data adheres to the expected format and includes the correct fields.
Supported actions
equals
notEquals
haveProperty
notHaveProperty
lengthOf
Example
name: "Validate the mail response field" key: json().textMail value: abc@gmail.com action: equals
This assertion checks if the
textMail
field in the JSON response equalsabc@gmail.com
. It passes if the value isabc@gmail.com
; otherwise, it fails.name: "Validate the response to contain a field" key: json() value: errors action: haveProperty
This assertion checks if the JSON response contains the
errors
field. It passes if the field exists; otherwise, it fails.name: "Validate the length response field" key: json().id value: 8 action: lengthOf
This assertion checks if the length of the
id
field in the JSON response is8
. It passes if the length matches8
; otherwise, it fails. - JSON – String
-
Supported actions
equals
notEquals
lengthOf
include
Example
name: "Validate the mail response field" key: json().textMail value: abc@gmail.com action: equals
This assertion checks if the
textMail
field in the JSON response equalsabc@gmail.com
. It passes if the value isabc@gmail.com
; otherwise, it fails.
This assertion checks if thename: "Validate the mail contains @gmail.com" key: json().textMail value: @gmail.com action: include
textMail
field in the JSON response contains@gmail.com
. It passes if the value includes@gmail.com
; otherwise, it fails.name: "Validate the length of the txn id" key: json().id value: 8 action: lengthOf
This assertion checks if the length of the
id
field in the JSON response is8
. It passes if the length matches8
; otherwise, it fails. - JSON – Number
-
Supported actions
equals
notEquals
lessThan
greaterThan
lengthOf
Example
name: "Validate the buildNumber response field" key: json().buildNumber value: 123 action: equals
This assertion checks if the
buildNumber
field in the JSON response equals123
. It passes if the value is123
; otherwise, it fails.name: "Validate the buildNumber" key: json().buildNumber value: 1000 action: lessThan
This assertion checks if the value of the
buildNumber
field in the JSON response is less than1000
. It passes if the value is smaller than1000
; otherwise, it fails.name: "Validate the length of the buildNumber" key: json().buildNumber.toString() value: 4 action: lengthOf
This assertion checks if the length of the
buildNumber
field (converted to a string) in the JSON response is4
. It passes if the length is4
; otherwise, it fails. - JSON – Object
-
Supported actions
equals
notEquals
haveProperty
notHaveProperty
Example
name: "Validate that the response equals the expected object" key: json() value: {"id": 12344533} action: equals
This assertion checks if the entire JSON response matches the expected object
{"id": 12344533}
. It passes if the response exactly equals this object; otherwise, it fails.name: "Validate that the response contains the 'errors' field" key: json() value: errors action: haveProperty
This assertion checks if the JSON response contains a field named
errors
. It passes if the field exists in the response; otherwise, it fails. - JSON – Array
-
Supported actions
lessThan
greaterThan
lengthOf
include
Example
name: "Validate the length of response field member" key: json().member value: 10 action: lengthOf
This assertion checks if the length of the
member
field in the JSON response is 10. It passes if the length of the field equals 10; otherwise, it fails.name: "Validate the length of response field member" key: json().member.length value: 10 action: lessThan
This assertion checks if the length of the
member
field in the JSON response is less than 10. It passes if the length of the field is fewer than 10; otherwise, it fails. - JSON schema
-
Verifies that the response body conforms to a defined JSON Schema, which specifies the expected structure and data types, ensuring the integrity of the response content.
Supported actions
validateSchema
inValidateSchema
Example
name: "Validate schema" key: json() value: {"type":object,"properties":{"id":"string"}} action: validateSchema
This assertion validates that the JSON response conforms to the specified schema. It checks that the response is an object with a property
id
of type string. The assertion passes if the response matches the schema; otherwise, it fails. - XML content
-
Validates the structure and content of XML responses, confirming that the data follows the expected XML format and contains the appropriate elements and attributes.
Supported actions
equals
notEquals
haveProperty
notHaveProperty
Example
name: "Validate the XML response property" key: xml().apiResponse value: type action: haveProperty
This assertion checks if the XML response contains the property
type
under theapiResponse
field. It passes if the property exists; otherwise, it fails.name: "Validate the XML response" key: xml().apiResponse.type value: [ 'unknown' ] action: equals
This assertion checks if the value of the
type
property underapiResponse
in the XML response equalsunknown
. It passes if the value isunknown
; otherwise, it fails. - Plain text content
-
Validates raw text in responses that are not formatted as JSON or XML, ensuring that the text returned matches expectations, such as no error messages or invalid data.
Supported actions
equals
notEquals
include
lengthOf
Example
name: "Ensure the response message does not indicate an error" key: text() value: Error action: notEquals
This assertion checks if the response message does not contain the word
Error
. It passes if the message does not includeError
and fails ifError
is found in the message.
Supported validation actions
This table describes each supported validation action, what it validates, and the types of data it applies to.
Action | Description | Supported in |
---|---|---|
equals |
Check whether the actual value equals the expected value. | All types: Response code, time, status, headers, text, JSON, XML |
notEquals |
Check whether the actual value is not equal to the expected value. | All types |
include |
Check whether the actual value contains the expected value (substring or array element). | String, status, headers, text, arrays |
lengthOf |
Validate the length of a string, array, or numeric string. | String, arrays, numbers, status, text, headers |
lessThan |
Check whether the actual numeric value is less than the expected value. | Number, response code, time |
greaterThan |
Check whether the actual numeric value is greater than the expected value. | Number, response code, time |
haveProperty |
Check whether an object (JSON/XML/Header) contains the specified property. | JSON, XML, headers |
notHaveProperty |
Check whether the object does not contain the specified property. | JSON, XML, headers |
validateSchema |
Validate a JSON response against the expected JSON schema. | JSON |
inValidateSchema |
Make sure that the JSON response does not match the given schema. | JSON |