API Versioning Best Practices: Real Team Examples
Twilio maintains 14 active API versions. Stripe pins every customer to the version active on their signup date and has supported versions going back to 2011. GitHub's REST API runs three major versions in parallel and publishes deprecation headers 12 months before sunset. Your team is probably trying to get away with one — and debating whether the version goes in the URL, a header, or the accept type.
The versioning debate is really three separate decisions stacked into one argument: where the version lives, how breaking changes are scoped, and when old versions die. Getting one right doesn't save you if the other two are wrong. This is a playbook drawn from how the companies that actually run public APIs at scale handle it, plus what we see inside PanDev Metrics customers running internal APIs with 20-200 consumers.