Contract testing for external APIs you do not control

An API schema describes shapes, but a reliable integration also depends on status codes, headers, authentication, retry behavior, idempotency, ordering, rate limits, and error semantics. A client can parse a provider response and still be wrong if a 202 means work is asynchronous or if a timeout may have completed the side effect. Write the contract around the decisions your application makes, not only the fields a generator can see.

Separate what the provider promises from what your client assumes. Keep an integration adapter between the provider and business logic so a provider change does not spread through every route. The adapter can normalize dates, map errors, apply deadlines, and attach an idempotency key. Tests should protect that boundary and make the assumptions visible.

A consumer contract describes the smallest response and behavior the application needs. For a payment or messaging provider, that may include one success response, a validation error, a retryable outage, and an idempotency replay. Keep fixtures minimal and representative. A huge captured response can make a test pass while hiding that the client depends on an accidental field no one intended to guarantee.

Assert status, important headers, field types, nullability, and error categories. Do not assert the exact ordering of JSON keys or a provider-generated timestamp unless the contract says it matters. If a provider supports schema versions, include the version in the fixture and test how the adapter reacts to an unknown version.

Use a mock server or provider test mode for deterministic contract tests. It should be able to return malformed JSON, slow responses, rate limits, duplicate events, and a timeout after accepting a request. A mock that only returns success validates serialization but not resilience. Keep the mock behavior close to the documented provider contract and update it when a real incident reveals a new response.

For providers without a test environment, use a recorded fixture with secrets and personal data removed, plus a small live probe that performs a harmless operation. The probe should run with a restricted credential and a budget. Do not make production tests send a real email, create a charge, or mutate customer data merely to prove connectivity.

A provider can deploy independently while your revision is rolling out. Test the old and new client behavior against the known response shapes and preserve compatibility when you can. If a new field or enum value appears, the adapter should classify unknown values safely rather than crashing a shared worker. If a provider removes a field, your fallback should be explicit and observable.

Use a canary or percentage rollout for changes that alter request shape, headers, or retry behavior. Compare provider response categories, latency, and rate-limit consumption between revisions. Keep a fast rollback, but do not assume rollback restores the old integration state if the provider has already accepted a new request format. Idempotency and version negotiation reduce that risk.

Fixtures should contain placeholder tokens, synthetic IDs, and redacted payloads. Test that the adapter sends the correct authentication scheme and header names without printing the credential. A request snapshot tool should redact authorization, cookies, signatures, and payment data before storing output. Treat fixture repositories as production-accessible because they are often copied into CI logs and developer machines.

Rotate test credentials separately from production credentials and scope them to the provider's sandbox. When a contract test fails because a secret is missing, fail with a variable name and remediation, not with the value. A useful failure tells the engineer what behavior changed without creating another incident.

Record provider name, operation, response category, schema version, latency, retry count, and adapter version. Alert on new status classes, unknown enum values, malformed responses, and a change in rate-limit headers. Keep metrics bounded by operation and provider. A spike in 404s may be a provider route change, while a spike in 422s may be a validation contract change.

Assign an owner and review date to every external integration. Store the provider documentation link and the last successful probe in the runbook. When a contract changes, record whether the client was updated, the provider was contacted, or the integration was intentionally retired. An unowned dependency is an outage with no obvious first responder.

Test timeout after request acceptance, duplicate retry, expired credential, invalid response, rate limit, provider outage, partial batch failure, and cancellation. Assert bounded retries, idempotency-key reuse, safe error mapping, and no duplicate side effects. Use a fake clock to test deadlines and backoff. Verify that a worker can reconcile an ambiguous result before attempting a second mutation.

Contract testing is a way to preserve trust across an ownership boundary. Keep the adapter small, test the behavior that drives decisions, use safe fixtures, probe harmlessly, and observe drift. The provider may change without your release, but your service can still respond deliberately when the contract stops being true.

When a provider changes, update the adapter and its fixtures before changing business logic. The adapter should translate provider-specific errors, dates, status names, and pagination into a stable internal contract. That keeps the rest of the application from learning accidental details and makes a rollback possible while the provider issue is investigated.

Schedule a harmless provider probe and review its result with the same owner who reviews contract fixtures. A probe that passes only connectivity is not enough; it should exercise authentication, a safe request, response validation, and the expected rate-limit headers. Store the last known contract version and alert when a new shape appears.

Store representative success, pagination, rate-limit, validation, and outage responses with the provider version or date they represent. Validate both strict required fields and tolerant unknown fields so a harmless provider extension does not break production. Run the fixtures in CI and against a safe sandbox probe on a schedule. When a contract changes, the diff should identify the adapter code, user impact, and rollout or rollback decision before the new shape reaches live traffic.

Keep provider-specific translation behind an adapter and store fixtures for success, pagination, validation, authentication failure, rate limiting, and outage responses. Validate required fields strictly, tolerate documented extensions, and normalize provider dates, statuses, errors, and cursors into a stable internal contract.

Run fixtures in CI, compare sandbox responses on a schedule, and exercise malformed or unknown fields. Assert that provider changes fail at the adapter boundary with a useful diagnostic rather than corrupting business logic. Record contract version, provider request ID, response validation result, and rate-limit headers without storing tokens.

Own a harmless provider probe that checks authentication, response shape, pagination, and expected throttling. Alert on new shapes and maintain a compatibility or rollback adapter while the provider issue is resolved. If the provider is degraded, queue safe work, return a truthful status, and prevent retries from amplifying the outage.

Use the provider's versioned API contract, OpenAPI or JSON Schema where supplied, and contract-testing patterns. Keep fixtures tied to provider version or date so a passing test remains meaningful.