All insights
EngineeringProduct5 min read
Versioning APIs in public
There are many ways to version an API. Most of them work for the company and confuse the developer. The few that work for both share a clear stance.
API versioning is one of those topics that produces strong opinions because every choice is wrong in some way. URI versioning is ugly. Header versioning is invisible. Date-based versioning is precise but unfamiliar. There's no perfect answer — but there are some honest ones.
What works in practice
- Pick one scheme and document it loudly — developers can adapt to any of them, but not to inconsistency.
- Use major versions sparingly — every few years, not every quarter.
- Run multiple versions in parallel for a long deprecation window (at least a year).
- Make the cost of staying on an old version visible (rate limits, missing features) — but never zero.
What doesn't
Surprise version cutovers. Versioning in headers that nobody documents. Skipping versions entirely and breaking things "because it's a beta." Each of these costs developer trust in ways that take years to rebuild.
Your versioning strategy is a public statement about how seriously you take developer time. They notice.