API Versioning — Notes

Practical playbook

• Default to evolutionary changes for as long as possible.
• Bump major version only when behaviour changes or fields are removed.
• Run N + N-1 in production; never N-2.
• Track per-customer adoption per version; only sunset once usage is low.

Tooling

• OpenAPI / gRPC contracts in a versioned repo.
• Schema diff tools (oasdiff for OpenAPI, buf for Proto).
• Contract tests (Pact) run on PRs to surface accidental breaks.

Deprecation comms

• Deprecation: true + Sunset: <date> response headers (RFC 8594).
• API portal banner + changelog feed.
• Email customers at T-90, T-30, T-7 days.

API governance at scale

• One review group for breaking changes.
• Per-team API owners.
• Lint rules in CI for forbidden changes (renames, type changes).

Refs

• Stripe API versioning (date-based versions; legacy + adapter pattern).
• GitHub API media-type versioning.
• Google AIPs (API improvement proposals).
• "API Design Patterns" — JJ Geewax.
• RFC 8594 (Sunset header).