API Versioning, Deprecation and Backward Compatibility Questions

Situation & goal (one line)
I need a deprecation policy for a multi-repo API platform that prevents consumer breakage while enabling progress.

Policy overview & timeline

• Announcement phase (T0): Deprecation announced with rationale, docs, and migration guide.
• Maintenance phase (T0 → T0 + 6 months): Deprecated API remains fully supported; critical fixes only.
• Sunset warning (T0 + 3 months): First reminder; usage metrics included.
• Removal candidate (T0 + 6 months): Cutover window opens; final compatibility mirror for last 30 days.
• Removal (T0 + 7 months): API removed after final notice and exec sign-off.
  (Adjustable per risk: minor deprecations can be 3–4 months; breaking, high-risk require 9–12 months.)

Communication practices

• Multi-channel: GitHub issue + repo deprecation file, release notes, docs site banner, engineering Slack, internal mailing lists, and monthly partner syncs.
• Clear artifacts: Deprecation RFC, migration checklist, estimated effort, and example code.
• SLA for responses: engineering team triages migration questions within 48 hours.

Compatibility layers & mitigations

• Provide versioned endpoints and a backwards-compat shim in gateway for 1–3 months post-removal candidate.
• Feature flags to toggle new behavior per consumer.
• Client libraries: maintain semver-major for breaking changes and provide timed side-by-side releases (old and new clients).

Automation & detection

• Instrumentation: require all APIs emit consumer-id headers and log usage to central telemetry.
• Automated jobs: weekly detection pipeline that lists active consumers of deprecated endpoints, notifies owners, and opens tracker issues.
• CI enforcement: linting that flags uses of deprecated SDK methods across repos (fail CI after grace period).
• Dashboards & alerts: show active consumers, error rates, and migration progress; escalate if high-volume users remain.

Metrics & governance

• Success metrics: % of consumers migrated by T+3 months, number of runtime breaks post-removal (target 0), time-to-migrate for top-10 consumers.
• Governance: Deprecation decisions approved by API steering group; exceptions logged and timeboxed.

Trade-offs
Longer timelines reduce risk but increase maintenance cost. Compatibility shims speed transition but add technical debt — require a retirement plan and budgeted effort.

I’d implement this policy as part of repo onboarding, enforce via CI/OSS templates, and review after first year to tune timelines and automation.

Situation & Goal
I led a platform team planning a breaking public API change used by many external clients. Goal: make the change while minimizing client outages and enabling fast rollback.

Plan (high-level)

• Announce timeline, migration guide, SDK updates, and deprecation window (6–12 months) to clients and account managers.
• Publish OpenAPI diffs and sample code.

Compatibility & Versioning

• Introduce a new major version (v2) while keeping v1 supported during the deprecation window.
• Use header-based version negotiation (Accept: application/vnd.myapi.v2+json) to avoid URL churn.

Migration mechanics

• Dual-write/dual-read on the server for internal traffic: write to both v1-compatible and v2 models for a defined period to validate parity.
• Provide an adapter/mapping layer for incoming v1 requests routed to v2 internals to reduce duplicate logic.
• Publish client-side adapters/compatibility middleware in official SDKs.

Release controls

• Gate v2 behavior behind feature flags and rollout in stages:
  • Canary 1: 0.5% internal traffic and 1–2 trusted partners
  • Canary 2: 5% external random clients
  • Progressive ramp: 25% → 50% → 100% over days/weeks, with manual approval between steps.

Monitoring & Success Criteria
Track metrics with thresholds:

• Error rate (4xx/5xx) per client and aggregate
• Latency P50/P95/P99
• API usage volume and conversion of clients to v2
• Business KPIs: signups, transactions tied to API flows
• Schema validation failures, payload size regressions
• Logs for adapter mismatches and data-parity diffs

Alerting: trigger if error rate increases >1% absolute or latency P95 increases >30% vs baseline, or if any high-severity customer reports.

Rollback criteria & plan

• Automatic hold and rollback if thresholds breached during ramp
• Immediate rollback steps: flip feature flag to route to v1/adapter, disable dual-write after validation, notify clients and execs
• Postmortem within 48 hours with remediation and adjusted timeline

Communication & Team Ops

• Dedicated migration runbook, playbook, and on-call rotation during rollout windows
• Weekly client migration office hours and status dashboard
• Measure adoption and retire v1 only after 80–90% client migration and stable metrics for 2–4 weeks

This approach balances safety, observability, clear client communication, and an operational plan for fast rollback while enabling iteration.