API Contract Checklist Before You Ship

Quick answer

Run contract checks at two gates: before coding and before release. Validate request/response shape, error envelope, permission outcomes, idempotency behavior, and backward compatibility. A contract is only safe when consumers can upgrade without guessing.

Contract checklist by area

• Request schema: required fields, defaults, limits, format validation.
• Response schema: stable names, nullable policy, enum expansion policy.
• Error model: standardized code/message/traceId and status mapping.
• Auth and permissions: expected result per role and token state.
• Pagination/filtering: deterministic order and token semantics.
• Write safety: idempotency keys, retry behavior, conflict handling.

Breaking changes to catch early

• Renaming a response field in place instead of adding a new field.
• Changing nullable to non-nullable without version boundary.
• Returning different error shapes across endpoints.
• Changing default sort order without documenting migration impact.

These changes often pass internal tests but break external consumers silently.

Review template you can reuse

# API Contract Review: POST /v1/orders

## Request Contract
- customerId: string, required, max 64
- items: array, required, min 1
- idempotencyKey: string, required for retries

## Response Contract
- 201: { orderId, status, createdAt }
- 400: validation error envelope
- 401: unauthorized envelope
- 409: conflict envelope
- 5xx: retry-safe error envelope

## Compatibility Rules
- v1 is add-only for response fields
- no field rename or semantic change in-place
- enum extensions must be documented before release

## Operational Notes
- duplicate idempotencyKey returns same orderId
- request timeout is safe to retry with same key

Release gate criteria

• Contract tests pass for success, validation, auth, and conflict paths.
• Consumer-impacting changes are announced and versioned.
• Rollback keeps previous contract behavior available.
• Monitoring can detect response-code or schema anomalies.

Breaking change taxonomy

Not all contract changes are equal. Some are safe to ship without a version boundary. Others will break consumers immediately. The distinction matters for release planning, consumer communication, and rollback strategy.

Additive changes are safe to ship without a version boundary: adding a new optional response field, a new optional request parameter, a new enum value that consumers can ignore, or a new endpoint. Changes that require versioning include renaming an existing field, changing a field from optional to required, removing a previously returned field, or changing the semantic meaning of an existing field without renaming it.

Some changes are immediately breaking: removing an existing endpoint, changing a required field type, changing authentication scheme, or altering error envelope structure. The most dangerous category is silently breaking changes — changing default sort order, pagination cursor format, numeric precision on monetary fields, or timezone assumptions on datetime fields.

The "silently breaking" category is the most dangerous because it passes all existing tests. Changing a datetime field from UTC to local time may look like a minor adjustment internally but breaks every consumer that stores or displays that value. These changes require a coordinated rollout with consumer notification, not just a version bump.

Consumer-driven contract testing

A producer-side contract test verifies that your API matches your own OpenAPI spec. That is necessary but not sufficient. Consumer-driven contract testing goes one step further: each consumer publishes what it actually uses from the API — the fields it reads, the status codes it handles, the error shapes it parses — and the producer runs that consumer's expectation set on every build.

• Tools like Pact allow consumers to define their expectations as a contract file that the producer verifies in CI.
• Consumer contracts catch the real breaking changes — the ones that don't appear in the spec because the consumer behavior was never documented.
• When a new consumer is onboarded, they publish their contract before the producer builds the feature, not after.
• Failing consumer contract tests should block the producer's release, not just generate a warning.

Consumer-driven testing is particularly valuable for internal microservice APIs where "all consumers are on our team" is used to justify skipping contract formalization. Internal teams move fast and change behavior in ways that are invisible to other teams until something breaks in staging or production.

Versioning decision checklist

The decision to version an API endpoint is often made reactively — after a breaking change has already been shipped. This checklist makes the versioning decision explicit before the change is written, not after it causes a consumer incident.

# Versioning Decision Gate

Is the change additive only?
  Yes -> no version change required; document new field in changelog

Does the change modify existing field behavior?
  Yes -> version boundary required; deprecate old behavior with timeline

Do all consumers need to adopt simultaneously?
  Yes -> coordinated rollout with migration guide; no immediate removal
  No  -> support old and new behavior in parallel for migration window

Will the old behavior be removed?
  Yes -> set removal date; notify consumers; add deprecation header to old endpoint
  No  -> maintain indefinitely; document support commitment

Is rollback possible after the new version ships?
  Yes -> document rollback procedure and data compatibility impact
  No  -> treat as irreversible migration; require explicit sign-off before release

Use these templates

Related articles

• Contract Testing: OpenAPI to CI
• API Versioning Strategies
• Error Handling Patterns for APIs
• Frontend–Backend Alignment