Review API Contract Changes Before Merge

Diff the OpenAPI document, classify changes as breaking or compatible, collect consumer impact, and require a migration plan for breaking changes.

intermediate~30 minapicontractsci-cd

Objective

Prevent an API change from breaking consumers silently, while allowing compatible evolution at normal speed.

Environment

An OpenAPI or equivalent machine-readable contract in the repository
A contract diff tool in CI
A list of known consumers and their owners
A deprecation and versioning policy

Steps

1. Diff the contract

Compare the proposed OpenAPI document with the base branch and list added, removed, and changed operations, parameters, and schemas.

Expected state: The diff is attached to the pull request and reviewed.

2. Classify each change

Mark additions as compatible and removals, required additions, type changes, and behavior changes as breaking.

Expected state: Every breaking change is identified before merge.

3. Assess consumer impact

Identify consumers of affected operations, notify their owners, and collect acknowledgement or a migration plan.

Expected state: No breaking change merges without an owner and a date.

4. Gate the merge

Fail CI on unapproved breaking changes; allow compatible changes with normal review.

Expected state: The contract and the implementation change together.

5. Record the decision

Link the migration plan, deprecation date, and successor version in the pull request and the API changelog.

Expected state: The change is traceable after release.

Decision points

Is an additive optional field always compatible?

Yes, if consumers tolerate unknown fields
No, check consumer parsers

Verify tolerant parsing; strict clients can break on unknown fields even when the schema is additive.

When should a new API version be created?

For any breaking change
Only for major redesigns

Use a new version when the old behavior cannot be preserved; otherwise deprecate in place with a migration window.

Expected outcome

Compatible changes ship normally, and breaking changes ship only with consumer awareness and a migration path.

Verification

Run the contract diff on the pull request, confirm the classification matches the policy, and verify the published contract and implementation agree after merge.

Cleanup

Update the changelog, close migration tasks, and remove the old version after its sunset date.

Make the diff a review artifact

An API change should be visible before merge. Generate a diff between the proposed contract and the base branch, and attach it to the pull request. A reviewer can then see a removed field or a new required parameter instead of discovering it in a client incident.

oasdiff breaking base.yaml head.yaml

The command is an example; any diff tool that classifies breaking changes works. The important part is that the classification is explicit and enforced.

Classify with the consumer in mind

Adding an optional field is usually compatible, but a strict client that rejects unknown fields can still break. Removing a field, adding a required field, changing a type, or changing error behavior is breaking. Check the policy and the known consumers rather than relying on the schema alone.

Gate breaking changes

Fail CI when a breaking change lacks an approval and a migration plan. Require the owner of each affected consumer to acknowledge. Publish the deprecation date and the replacement. After the sunset, remove the old behavior and update the contract.

Verify after merge

Confirm the deployed API matches the merged contract, and that generated clients or docs were regenerated. A contract that passes review but drifts from the implementation is worse than no contract; add a contract test or a schema check against a running service.