DEV Community

Cover image for The Only 3 Types of Assertions You Need for REST API Tests
Sushant Joshi
Sushant Joshi

Posted on

The Only 3 Types of Assertions You Need for REST API Tests

#ai #api #startup #testing

I went through 2,400 of our team's API test assertions last month. 91% of them fall into three categories.*

That number surprised me.

Not because it was low.

Because it was so high.

I expected to find dozens of assertion patterns:

  • Header assertions
  • Pagination assertions
  • Security assertions
  • Performance assertions
  • Database validations
  • Custom business rules

Instead, almost everything we had written could be grouped into just three buckets.

When I removed duplicate patterns and categorized the assertions, 91% of them fit into:

  1. Schema Assertions
  2. Identity Assertions
  3. Side-Effect Assertions

The remaining 9%?

Most of them probably shouldn't exist.

If you're building or maintaining REST API tests, understanding these three categories will dramatically simplify how you think about testing.

Why Most API Test Suites Become Hard to Maintain

A lot of test suites grow organically.

A developer writes:

expect(response.status).toBe(200);
Enter fullscreen mode Exit fullscreen mode

Another adds:

expect(response.body.name).toBe('John');
Enter fullscreen mode Exit fullscreen mode

Someone else adds:

expect(response.body.items.length).toBe(3);
Enter fullscreen mode Exit fullscreen mode

Eventually the suite contains thousands of assertions.

Many of them:

  • Duplicate each other
  • Validate implementation details
  • Add maintenance without adding confidence

The goal isn't to write more assertions.

The goal is to write the assertions that actually matter.

1. Schema Assertions (The One Most Tests Skip)

This is the most undervalued type of API assertion.

A schema assertion answers:

Does the response still match the contract?

Suppose your endpoint returns:

{
  "id": 123,
  "name": "John Smith",
  "email": "john@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Tomorrow someone changes it to:

{
  "id": "123",
  "fullName": "John Smith"
}
Enter fullscreen mode Exit fullscreen mode

The endpoint still returns:

200 OK
Enter fullscreen mode Exit fullscreen mode

But consumers may immediately break.

This is why schema assertions matter.

What Schema Assertions Validate

  • Required fields exist
  • Data types are correct
  • Fields have not disappeared
  • Arrays contain the right structure
  • Response contracts remain compatible

Example JSON Schema Assertion 

expect(response.body).toMatchSchema({
  type: 'object',
  required: ['id', 'name'],
  properties: {
    id: {
      type: 'integer'
    },
    name: {
      type: 'string'
    }
  }
});
Enter fullscreen mode Exit fullscreen mode

Why Teams Skip This

Because checking:

expect(response.status)
  .toBe(200);
Enter fullscreen mode Exit fullscreen mode

feels sufficient.

It isn't.

The biggest API regressions I see are contract changes that still return successful responses.

This is why json schema assertion techniques provide so much value.

Copy-Paste Template: Schema Assertion 

expect(response.body)
  .toMatchSchema(schema);
Enter fullscreen mode Exit fullscreen mode

Or:

expect(response.body.id)
  .toEqual(expect.any(Number));
Enter fullscreen mode Exit fullscreen mode

2. Identity Assertions (The Value You Actually Care About)

This is the category most people think of when they hear "API testing."

An identity assertion answers:

Did the API return the correct business value?

Example:

{
  "discount": 20
}
Enter fullscreen mode Exit fullscreen mode

The contract may be valid.

The endpoint may return 200.

But if the expected discount is:

{
  "discount": 50
}
Enter fullscreen mode Exit fullscreen mode

the API is still broken.

Identity Assertions Validate

  • Business calculations
  • Field values
  • Sorting
  • Filtering
  • Authorization decisions
  • Domain rules

Example 

expect(response.body.discount)
  .toBe(20);
Enter fullscreen mode Exit fullscreen mode

Or:

expect(response.body.status)
  .toBe('ACTIVE');
Enter fullscreen mode Exit fullscreen mode

Why Identity Assertions Matter

Customers care about values.

They do not care that:

{
  "discount": {
    "type": "integer"
  }
}
Enter fullscreen mode Exit fullscreen mode

is valid.

They care that the discount is correct.

Copy-Paste Template: Identity Assertion 

expect(response.body.field)
  .toBe(expectedValue);
Enter fullscreen mode Exit fullscreen mode

Or:

expect(response.body)
  .toEqual(expectedObject);
Enter fullscreen mode Exit fullscreen mode

3. Side-Effect Assertions (The Ones That Prove the Work Happened)

This category gets overlooked surprisingly often.

An API can return:

200 OK
Enter fullscreen mode Exit fullscreen mode

and still fail completely.

Consider:

POST /orders
Enter fullscreen mode Exit fullscreen mode

The endpoint returns success.

But:

  • The database row wasn't created.
  • The message wasn't published.
  • The email wasn't sent.

The business process failed.

Side-Effect Assertions Validate

  • Database writes
  • Queue messages
  • Event publication
  • Emails
  • Audit logs
  • Third-party integrations

Example Database Assertion 

expect(orderRepository.find(orderId))
  .not.toBeNull();
Enter fullscreen mode Exit fullscreen mode

Example Queue Assertion 

expect(queue.contains(orderCreatedEvent))
  .toBe(true);
Enter fullscreen mode Exit fullscreen mode

Why Side Effects Matter

Many APIs exist solely to trigger something else.

The response itself is often the least important part.

For example:

POST /payments
Enter fullscreen mode Exit fullscreen mode

Nobody cares about:

{
  "success": true
}
Enter fullscreen mode Exit fullscreen mode

What matters is:

  • Was the payment captured?
  • Was the invoice generated?
  • Was the receipt sent?

Copy-Paste Template: Side-Effect Assertion 

expect(databaseRecord)
  .toExist();
Enter fullscreen mode Exit fullscreen mode

Or:

expect(publishedEvent)
  .toBeDefined();
Enter fullscreen mode Exit fullscreen mode

The 9% That Didn't Fit

After categorizing our assertions, around 9% remained.

Examples included:

expect(response.body.items.length)
  .toBe(5);
Enter fullscreen mode Exit fullscreen mode 
expect(response.body.createdAt)
  .toBe('2026-07-01');
Enter fullscreen mode Exit fullscreen mode 
expect(response.body.version)
  .toBe('1.2.8');
Enter fullscreen mode Exit fullscreen mode

Many of these were:

  • Brittle
  • Overly specific
  • Tied to implementation details

Why Most of Them Should Be Deleted

Ask yourself:

If this assertion failed tomorrow, would users actually notice?

If the answer is:

Probably not.

Delete it.

A surprising amount of maintenance comes from assertions that don't provide meaningful confidence.

Bad Assertions 

expect(responseTime)
  .toBe(183);
Enter fullscreen mode Exit fullscreen mode 
expect(itemCount)
  .toBe(17);
Enter fullscreen mode Exit fullscreen mode 
expect(timestamp)
  .toEqual('2026-07-28T08:00:00Z');
Enter fullscreen mode Exit fullscreen mode

These tend to break constantly.

Better Assertions 

expect(responseTime)
  .toBeLessThan(500);
Enter fullscreen mode Exit fullscreen mode 
expect(itemCount)
  .toBeGreaterThan(0);
Enter fullscreen mode Exit fullscreen mode 
expect(timestamp)
  .toBeDefined();
Enter fullscreen mode Exit fullscreen mode

These are more resilient.

The Assertion Pyramid I Recommend

Whenever I write a new API test, I ask three questions.

First

Does the response still match the contract?

→ Schema Assertion.

Second

Did the API return the correct business value?

→ Identity Assertion.

Third

Did the system actually perform the work?

→ Side-Effect Assertion.

Most useful tests contain at least one of these categories.

Many contain all three.

Example:

expect(response.body)
  .toMatchSchema(userSchema);

expect(response.body.name)
  .toBe('John');

expect(databaseUser)
  .toExist();
Enter fullscreen mode Exit fullscreen mode

Three assertions.

Three different guarantees.

High confidence.

Low maintenance.

Final Thoughts

When we reduced our thousands of assertions down to categories, we realized something important:

Most API testing is simpler than we make it.

The majority of valuable assertions answer only three questions:

  1. Is the contract still valid?
  2. Is the business value correct?
  3. Did the side effect happen?

Everything else should justify its existence.

If an assertion doesn't increase confidence or protect against meaningful regressions, it may not belong in the suite.

That's why I now start every API test by deciding which of these three categories I'm actually trying to validate.

If you'd like to go deeper into building maintainable API suites, I highly recommend the REST API testing best practices guide:

https://totalshiftleft.ai/blog/rest-api-testing-best-practices

Because the best API tests aren't the ones with the most assertions.

They're the ones with the right assertions.

Top comments (0)