Design an API versioning strategy that enables evolution without breaking existing consumers.
## CONTEXT Breaking API changes are the number one cause of developer churn in platform ecosystems — a study by ProgrammableWeb found that 38% of developers abandoned an API after a poorly managed breaking change. Meanwhile, maintaining multiple API versions indefinitely costs organizations 20-40% more in engineering overhead per active version. The tension between evolving your API and maintaining backward compatibility is one of the hardest problems in platform engineering, and getting the versioning strategy wrong either freezes your API in time or destroys the trust of your developer community. ## ROLE You are an API platform architect with 15 years of experience managing API lifecycle, backward compatibility, and multi-version support across ecosystems with thousands of consumers. You led API versioning strategy at a platform serving 30,000 developers where you managed 4 concurrent API versions with zero unplanned breaking changes over a 5-year period. Your versioning framework has been adopted by organizations that reduced version-related support tickets by 85% and compressed consumer migration timelines from 12 months to 90 days. You understand that versioning is not just a technical decision — it is a contract with your developer community that requires as much communication strategy as engineering design. ## RESPONSE GUIDELINES - Recommend a versioning approach based on the specific consumer count, deployment model, and change frequency — not a generic "best practice" - Define backward compatibility rules with exhaustive examples of what is and is not a breaking change - Include concrete timelines for deprecation, migration windows, and sunset dates calibrated to the consumer base size - Design the communication plan with specific templates for announcements, migration guides, and sunset notices - Do NOT recommend a versioning approach without analyzing its trade-offs against the alternatives for this specific use case - Do NOT treat versioning as purely technical — the developer relations and communication components are equally critical ## TASK CRITERIA 1. **Versioning Approach Selection** — Evaluate URI path versioning (/v1/), header versioning (Accept-Version), query parameter versioning (?version=1), and content negotiation against the specific requirements. Present a pros/cons matrix for each approach considering: developer experience, cacheability, routing complexity, and discoverability. Recommend one with detailed justification. 2. **Version Numbering Scheme** — Define the numbering convention (major.minor, date-based, sequential) and the exact criteria for incrementing each level. Specify which types of changes require a new major version, which are minor additions within a version, and which are patches that require no version change. 3. **Breaking Change Definition** — Create an exhaustive classification of changes as breaking vs. non-breaking. Include: field removal, field renaming, type changes, enum value removal, response structure changes, authentication changes, default value changes, and behavior changes. Provide concrete examples for each category. 4. **Backward Compatibility Contract** — Define the rules that the API team must follow to maintain backward compatibility: additive changes only within a version, optional fields defaulting gracefully, deprecated fields continuing to function, and response envelope stability. Include a pre-release checklist. 5. **Deprecation Policy and Timeline** — Design the complete deprecation lifecycle: announcement date, deprecation marker activation, migration window duration, sunset warning period, and final shutdown. Calibrate timelines to the consumer base size — 100 consumers need different windows than 10,000. 6. **Sunset Header Implementation** — Specify the Sunset HTTP header implementation: header format (RFC 8594), when it starts appearing, how it interacts with monitoring and logging, and how consuming developers can programmatically detect approaching sunsets. 7. **Migration Guide Template** — Create a reusable migration guide structure: summary of changes, step-by-step migration instructions, code comparison examples showing old vs. new patterns, breaking change impact assessment, and a testing checklist for verifying migration completeness. 8. **Consumer Communication Plan** — Design the multi-channel communication strategy: email announcements, developer portal changelog updates, in-response deprecation warnings, dashboard notifications, and developer community posts. Include templates for each communication type. 9. **Parallel Version Infrastructure** — Address the engineering cost of maintaining multiple versions: shared vs. duplicated codebases, routing configuration, testing requirements per version, monitoring per version, and the decision criteria for when to force-sunset an old version. 10. **Version Decision Framework** — Create a decision matrix that the team uses for every planned change: when to extend the current version with an additive change, when to create a new minor version, and when a new major version is warranted. Include a flowchart with specific decision criteria. ## INFORMATION ABOUT ME - My API name: [INSERT API NAME — e.g., PaymentFlow API, ConnectHub API] - My current version: [INSERT CURRENT VERSION — e.g., v2, v1.3, 2024-01-15] - My consumer count: [INSERT CONSUMER COUNT — e.g., 50 internal teams, 500 third-party developers, 5000+ public consumers] - My planned breaking changes: [INSERT BREAKING CHANGES — e.g., restructuring response format, removing legacy fields, changing auth from API keys to OAuth] - My deployment model: [INSERT DEPLOYMENT MODEL — e.g., cloud SaaS continuous deployment, on-premise quarterly releases, API gateway managed] - My consumer migration capacity: [INSERT MIGRATION CAPACITY — e.g., consumers can migrate within 30 days, some consumers have 6-month release cycles] ## RESPONSE FORMAT - Open with a versioning strategy summary recommending the approach, numbering scheme, and key lifecycle milestones in 5-7 sentences - Present the versioning approach comparison as a pros/cons matrix table - Include the breaking change classification as a detailed reference table with categories, examples, and verdicts - Provide a deprecation timeline visualization showing each lifecycle phase with durations - Include communication templates for: initial announcement, deprecation notice, migration reminder, and sunset warning - Close with the version decision flowchart and a governance checklist for the API team to follow before releasing any change
Or press ⌘C to copy