Prompt file imported from cdalsoniii/brightpath-coder (.cursor/commands/api-breaking-change-check.md). Copyright stays with the author.

API Breaking Change Check

Overview

Detect breaking API changes between versions.

Steps

1. Compare current API spec with previous version

   • Load current API specification (OpenAPI, GraphQL schema, or code definitions)
   • Load previous version specification for comparison
   • Use diff tool or API comparison library to identify differences
   • Generate detailed change report showing all modifications

2. Identify breaking changes

   • Detect removed endpoints or methods
   • Find changed request schemas (added required fields, removed fields, type changes)
   • Identify narrowed response types (removed fields, stricter types)
   • Check for changed status codes or error formats
   • Flag any authentication or authorization requirement changes

3. Classify each change

   • Mark changes as breaking (incompatible with previous version)
   • Mark changes as non-breaking (backward compatible additions)
   • Identify deprecations (features marked for removal in future version)
   • Document semantic changes (behavior changes without schema changes)
   • Categorize by impact level (critical, major, minor)

4. Assess consumer impact for each breaking change

   • Identify which consumers use affected endpoints
   • Estimate number of affected API calls or integrations
   • Evaluate migration effort required for each consumer
   • Assess business impact of breaking changes
   • Prioritize changes by impact severity

5. Recommend migration path or versioning strategy

   • Suggest versioning approach (URL path, header, query param)
   • Recommend deprecation timeline with sufficient notice period
   • Provide migration guide for breaking changes
   • Suggest feature flags or gradual rollout strategy
   • Document backward compatibility guarantees

Checklist

• Current and previous API specifications are compared
• All breaking changes are identified and documented
• Changes are classified as breaking, non-breaking, or deprecation
• Consumer impact is assessed for each breaking change
• Migration path or versioning strategy is recommended
• Breaking changes are prioritized by impact severity
• Deprecation timeline provides sufficient notice period

References

• Rules:
  • .cursor/rules/088-api-versioning.mdc
  • .cursor/rules/api-design-standards.mdc
• Plans:
  • .cursor/plans/api_design_versioning_strategy.plan.md
• Skills:
  • .cursor/skills/api-versioning/SKILL.md