API Contract Testing for Integrations

A connector that worked yesterday fails this morning. The cause turns out to be a small change on the other side: a field renamed, a status value added, a date returned in a new format. Nobody intended to break anything, and nobody tested the combination before release. API contract testing is designed to catch exactly this. It checks that the requests a consumer sends and the responses it expects still match what the provider actually does, and it does so in each build rather than in a fragile end-to-end environment. This guide explains how contract tests work, the two main approaches, and where they fit in integration projects.

What API contract testing checks

A contract is the shared understanding between a consumer, such as a connector or app, and a provider, such as an API. It covers:

• Which endpoints the consumer calls, with which methods and parameters
• Which request fields it sends, with which types and formats
• Which response fields it relies on, with which types and values
• Which status codes and error formats it handles

API contract testing verifies both sides of that understanding: the consumer only sends what the provider accepts, and the provider still returns what the consumer relies on.

The Pact documentation describes contract tests as asserting that inter-application messages conform to a shared understanding that is documented in a contract, and notes that without contract testing, the only way to ensure applications work together is expensive and brittle integration testing.

Why not just run end-to-end tests?

End-to-end tests are valuable but have limits for integrations:

• They need every system running at once, with suitable test data
• They are slow, so teams run them rarely
• Failures are hard to diagnose, because any component could be at fault
• Third-party systems may not offer test environments at all

Contract tests are narrower and faster. Each side is tested on its own, against the contract, so failures point directly to the change that broke the agreement. They complement end-to-end tests rather than replacing them. Our guide to Zoho CRM integration testing covers the broader test strategy for CRM-connected systems.

Approach 1: consumer-driven contracts

In consumer-driven contract testing, the consumer's tests define what it needs from the provider:

1. The consumer's unit tests run against a mock provider and record the interactions they rely on
2. These interactions are saved as a contract file
3. The provider's build replays the contract against the real provider code and checks that each response matches
4. If the provider changes in a way that breaks a consumer's contract, its build fails before release

Pact describes itself as a code-first, consumer-driven contract testing tool, generally used by developers and testers who code. This approach works best when both consumer and provider are developed by teams you can coordinate with, such as internal services and your own connectors.

Approach 2: specification-based contracts

The second approach uses an API specification as the contract. The OpenAPI Specification defines a standard, programming language-agnostic interface description for HTTP APIs. Contract tests can:

• Check that the provider's actual responses match its published OpenAPI document
• Check that the consumer's requests and response handling match the same document
• Compare a new version of the specification with the old one to flag breaking changes

This approach suits third-party APIs, where you cannot run the provider's build. You test your connector against the provider's published specification, and re-check whenever the specification changes.

Contract testing third-party APIs

Most SaaS vendors will not run your contract tests. You can still protect yourself:

• Write contract tests for the parts of each third-party API your connector uses
• Run them against the vendor's sandbox on a schedule, not just at release time
• Compare new versions of the vendor's specification, where published, with the previous one
• Treat failures as early warnings of upstream changes, before production traffic is affected

Worked example: an API contract testing plan

The table below shows a hypothetical plan for a connector that syncs orders between an internal orders API and a third-party accounting system. Choices are illustrative.

InterfaceProvider ownerContract approachWhen tests runOn failureConnector to internal orders APIInternal teamConsumer-driven contractsEvery build of either sideBlock provider releaseConnector to accounting APIThird-party vendorTests against vendor OpenAPI and sandboxDaily and before each connector releaseAlert connector ownerWebhook from orders API to connectorInternal teamConsumer-driven message contractEvery build of either sideBlock provider releaseAccounting API specificationThird-party vendorDiff of new and previous specWhen vendor publishes changesReview changes, update tests

In this plan, the internal interfaces get the strongest protection because both sides can be tested in their builds. The vendor interface relies on scheduled checks and specification comparison.

What to include in contracts

Keep contracts focused on what the consumer actually uses:

• Required fields and their types, not every field the provider returns
• Value sets that matter, such as status codes the consumer maps
• Error responses the consumer handles, such as validation errors and not found
• Message formats for webhooks or queue events, not just HTTP calls

Over-specified contracts break on harmless changes, such as a new optional field, and teams start ignoring failures.

Fit contract tests into delivery

• Store contracts where both teams can access them, such as a shared repository or a contract broker
• Run provider verification in the provider's continuous integration pipeline
• Version contracts with the consumer's releases
• Make contract failures block deployment for internal interfaces
• Review contract coverage when adding new integration features

Contract testing also supports safer migrations. Our guide to CRM migration testing explains how to validate data and integrations when moving between systems.

Start small

You do not need contracts for every interface on day one. Begin with the integration that breaks most often or carries the most value, write contracts for the handful of interactions it relies on, and get them running in the build. Once the team sees a contract failure catch a real change before release, extending the approach to other interfaces becomes much easier to justify.

Common mistakes

• Contracts that copy entire responses instead of the fields the consumer uses
• Running contract tests only occasionally, so breaking changes slip through
• Treating contract tests as a replacement for all other integration testing
• No owner for failures from third-party contract checks

Frequently Asked Questions

What is API contract testing?

It checks that a consumer's requests and expectations match what an API provider actually accepts and returns, testing each side separately against a shared contract.

How is contract testing different from end-to-end testing?

Contract tests check each side against the contract in isolation and run quickly in every build. End-to-end tests run all systems together and are slower and harder to diagnose.

Can you contract test third-party APIs?

Yes, partly. Test your connector against the vendor's published specification and sandbox on a schedule, and compare new specification versions with previous ones.

What is consumer-driven contract testing?

It is an approach where the consumer's tests define the interactions it relies on, saved as a contract that the provider verifies in its own build before releasing changes.

Catch breaking changes before production

We add contract tests to connectors and internal APIs, set up specification checks for third-party APIs and build them into your release process. See our CRM and API integration services, or talk to us about contract testing.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.