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 matches 201; 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 than 2000; 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 matches OK; 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 value application/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 equals abc@gmail.com. It passes if the value is abc@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 is 8. It passes if the length matches 8; 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 equals abc@gmail.com. It passes if the value is abc@gmail.com; otherwise, it fails.

name: "Validate the mail contains @gmail.com"
key: json().textMail
value: @gmail.com
action: include
This assertion checks if the 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 is 8. It passes if the length matches 8; 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 equals 123. It passes if the value is 123; 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 than 1000. It passes if the value is smaller than 1000; 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 is 4. It passes if the length is 4; 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 the apiResponse 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 under apiResponse in the XML response equals unknown. It passes if the value is unknown; 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 include Error and fails if Error 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