How an API evolves over time without breaking existing clients, the discipline that decides who pays the upgrade cost.
API versioning is the discipline of evolving an API over time without breaking existing clients. Common approaches include URL versioning (/v1/users, /v2/users), header versioning (Accept: application/vnd.example.v2+json), and date-based versioning (Stripe's API-Version header set to a release date). Each style has tradeoffs in cache behavior, client implementation, and how aggressively old versions can be deprecated.
The hidden cost of public APIs is supporting old versions forever, every client is on a different version, deprecating any version triggers integration work in customer codebases. A clear versioning strategy from day one (typically date-based for the most flexibility) is dramatically cheaper than trying to retrofit one after thousands of clients are already integrated. Pair versioning with a deprecation policy (announce 12 months out, sunset on schedule) so the cost is bounded.
See the part of the platform that handles versioning (api versioning) in production.