API contract testing: where to start

A contract is the API’s promise

An API contract is an agreement between provider and consumer: which endpoints exist, what data they accept and what they return. It’s usually written down as an OpenAPI (Swagger) specification, a WSDL for SOAP or a GraphQL schema. The problem is that the specification and the actual behaviour drift apart faster than anyone notices.

In one API testing project I compared API responses with the Swagger documentation. Mismatches came up regularly: different field names, different types, optional fields that were required in practice.

Contract test vs integration test

• An integration test checks whether two systems work together: does an order placed in the app reach the warehouse.
• A contract test checks whether an API response has the promised shape: is status a string from a defined list, is createdAt an ISO 8601 date.

Contract tests are faster, more stable and point to the culprit more easily. When one fails, you know the API changed, not that the environment is broken.

JSON schema validation

The simplest contract test validates a response against a JSON Schema. In RestAssured it looks like this:

@Test
void orderMatchesContract() {
    given().auth().oauth2(token)
    .when().get("/api/orders/{id}", orderId)
    .then().statusCode(200)
        .body(matchesJsonSchemaInClasspath("schemas/order.json"));
}

You can generate order.json from OpenAPI and then tighten it: add required, allowed values (enum) and formats. Such a test catches a removed field, a type change and a new, undocumented status value.

In Postman you can do the same in the collection’s tests tab:

const schema = pm.collectionVariables.get("orderSchema");
pm.test("response matches the contract", () => {
  pm.response.to.have.jsonSchema(JSON.parse(schema));
});

Where to start

1. Pick 5-10 endpoints used by other teams or partners. That’s where a contract change hurts most.
2. Start with successful responses (200, 201). Then add errors: 400 with validation details, 401, 403, 404.
3. Keep schemas in the repository next to the tests. A contract change will show up in code review.
4. Run the tests on every backend change. Dozens of contract tests run in seconds.

Contract tests don’t replace business scenario tests. They check the shape of the data, not whether the logic is correct.

Negative tests

The contract covers errors too. Check that the API:

• rejects missing required fields with a clear message,
• doesn’t leak implementation details (stack traces, table names) in a 500 response,
• returns 401 without a token and 403 with a token that lacks permissions,
• respects length limits and value ranges.

Summary

Contract tests are the cheapest way to make sure a change in one service doesn’t break five others. Start by validating the schema of a few key endpoints and plug it into CI. If you need help with API testing, get in touch. If you’re looking for a team to design the backend and integrations, that’s what my company does: the software house 2Simple.