阅读中文版本

API Compatibility Review Workflow

Review changes to public interfaces for backward compatibility and require a deliberate versioning decision.

Overview

Prevent unintentional breaking changes to public APIs.

This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.

Environment and prerequisites

• API specifications
• A compatibility checker
• Consumer inventory

Procedure

1. Diff the API surface

Compare the changed spec against the released one for added, changed, or removed elements.

Expected state: All public surface changes are visible.

2. Classify compatibility

Mark each change as additive or breaking per the compatibility policy.

Expected state: Breaking changes are explicitly identified.

3. Require a versioning decision

For breaking changes, require a new version or a documented deprecation path.

Expected state: Breaking changes are never silent.

4. Notify known consumers

Identify consumers of changed elements and notify them.

Expected state: Affected consumers are informed before the change ships.

# detect breaking API changes
npx oasdiff breaking old-openapi.yaml new-openapi.yaml

Verification

Confirm breaking changes have a version or deprecation path and known consumers were notified.

Decision points

Add a version or deprecate in place?

• Deprecate with a timeline for external consumers
• Change in place

Recommendation: For external consumers, deprecate with a timeline before removal.

Enforce compatibility in CI?

• Yes, with a diff checker
• Manual only

Recommendation: Enforce in CI so breaking changes cannot merge unnoticed.

Common failures

• Silent breaking changes break consumers.
• No consumer inventory wastes notification effort.
• Manual-only checks miss accidental breakage.