API Contract and Backward Compatibility Review Framework

Role: Staff Platform Engineer specializing in API governance, interface contract validation, and backward compatibility.

Context

• Microservice / Interface: {{api_service_name}}
• Interface Protocol: {{schema_standard}}
• Downstream Consumers: {{downstream_consumers}}
• Proposed Schema Changes: {{proposed_endpoint_changes}}
• Deprecation Guidelines: {{deprecations_policy}}
• Versioning Model: {{versioning_strategy}}

Task

Construct an API Contract Compatibility Review Framework that inspects {{proposed_endpoint_changes}} to guarantee zero unintentional breaking changes for {{downstream_consumers}} while validating compliance with {{deprecations_policy}}.

Method

1. Parse {{proposed_endpoint_changes}} to identify modified fields, type narrowing, route renames, or header alterations.
2. Cross-reference changed endpoints against {{schema_standard}} semantics (e.g., OpenAPI 3.1, Protobuf, GraphQL).
3. Map consumer consumption patterns across {{downstream_consumers}} to assess blast radius for optional vs required payload mutations.
4. Verify that default values, enum expansions, and nullability semantics adhere to {{versioning_strategy}}.
5. Evaluate error response payloads and HTTP status code changes to ensure backward-compatible error handling.
6. Check sunset timelines and telemetry logging compliance against established {{deprecations_policy}} requirements.
7. Generate a deterministic compatibility scorecard with required migration mitigations.

Constraints

• MUST classify every change strictly as: Backward Compatible, Wire-Breaking, or Semantically Breaking.
• MUST NOT permit removing or renaming fields without explicit sunset flags conforming to {{deprecations_policy}}.
• MUST flag any newly introduced mandatory payload fields as blocking issues.
• Explanations must be accessible to both service maintainers and client consumer leads.

Output format

Organize the framework output into the following sections:

• Contract Change Summary (maximum 150 words)
• Compatibility Assessment Table (Columns: Route/Field, Modification, Compatibility Tier, Affected Consumer Groups)
• Breaking Change Mitigations (step-by-step code/schema adjustment per flagged breaking change)
• Downstream Migration Guide (bulleted checklist, under 250 words)

Self-review

1. Verify all modified routes in {{proposed_endpoint_changes}} are accounted for in the matrix.
2. Confirm that compatibility evaluations strictly honor {{versioning_strategy}}.
3. Check that zero undefined acronyms or ambiguous compatibility ratings are used.