Maeris logo
Get started for free

API Assertions and Validations

Learn how to add assertions and validations to your API requests to ensure they work correctly and return expected results.

What are Assertions?

Assertions are validations that check if your API responses meet your expectations. They verify that the API is working correctly by checking status codes, response times, response bodies, headers, and other aspects of the response.

Why Assertions Matter

  • Verify Correctness: Ensure APIs return expected data and status codes
  • Catch Regressions: Detect when APIs break or change unexpectedly
  • Documentation: Serve as executable documentation of expected behavior
  • Confidence: Give you confidence that your APIs work as intended
  • Automation: Enable automated testing and CI/CD integration

Types of Assertions

Status Code Assertions

Verify that the API returns the expected HTTP status code (200, 201, 404, 500, etc.).

Assert status code equals 200
Assert status code is between 200 and 299

Response Time Assertions

Check that the API responds within an acceptable time limit.

Assert response time is less than 1000ms
Assert response time is less than {{maxResponseTime}}

Response Body Assertions

Validate the content of the response body, including specific fields and values.

Assert response body contains "success"
Assert response.body.status equals "active"
Assert response.body.user.id exists

Header Assertions

Verify that response headers contain expected values.

Assert header Content-Type equals "application/json"
Assert header Authorization exists

Schema Assertions

Validate that the response matches a JSON schema or structure.

Assert response matches JSON schema
Assert response.body has required fields

Adding Assertions to Requests

  1. Open Request: Select the API request you want to add assertions to
  2. Navigate to Assertions Tab: Find the Assertions or Tests section in the request editor
  3. Add Assertion: Click "Add Assertion" or use the assertion builder
  4. Select Assertion Type: Choose the type of assertion you want to add
  5. Configure Assertion: Set the expected value or condition
  6. Save Assertion: Save the assertion to your request

Common Assertion Patterns

Success Response Validation

Assert status code equals 200
Assert response time is less than 2000ms
Assert response.body.success equals true
Assert response.body.data exists

Error Response Validation

Assert status code equals 404
Assert response.body.error exists
Assert response.body.message contains "not found"

Data Validation

Assert response.body.user.id is a number
Assert response.body.user.email matches email pattern
Assert response.body.items is an array
Assert response.body.items.length is greater than 0

Best Practices

  • Always Assert Status Codes: Verify that you get the expected status code
  • Validate Response Structure: Check that required fields exist and have correct types
  • Test Both Success and Error Cases: Don't just test happy paths
  • Use Meaningful Assertions: Assert things that matter for your use case
  • Set Response Time Limits: Ensure APIs respond within acceptable timeframes
  • Validate Data Types: Check that fields have the correct data types
  • Use Variables: Make assertions reusable by using variables
  • Document Assertions: Add comments explaining why assertions are important

Next Steps