Definition
Imagine you’re running a popular translation app. Thousands of other companies have built their software to work with your API. Now you want to add a great new feature, but it requires changing how your API responses are structured. If you just change it, you’ll break all those thousands of integrations overnight. Their apps will crash, their users will complain, and you’ll have a lot of angry customers.
API versioning solves this problem by letting you maintain multiple versions of your API simultaneously. Old clients can keep using the version they know (v1), while new clients can adopt the improved version (v2). You’re not forcing anyone to upgrade immediately - they can do it at their own pace, when they’re ready to update their code.
Think of it like maintaining different editions of a textbook. Students studying with the 3rd edition can still learn effectively, even though the 4th edition exists with updated content. Teachers don’t fail students for using an older edition; they give them time to transition. Similarly, API versioning gives your consumers time to adapt to changes without breaking their existing integrations.
Example
Stripe API: Stripe is famous for their versioning approach. Instead of simple version numbers, they use dates like 2023-10-16. When you create a Stripe account, your API version is locked to that date. Stripe continues supporting old versions for years, and you can upgrade by changing a header or account setting when you’re ready.
Twitter/X API: When Twitter launched v2 of their API, they didn’t shut down v1 immediately. Developers had months (sometimes years) to migrate. Some endpoints existed in both versions simultaneously, giving developers flexibility to migrate gradually.
Google Cloud APIs: Google uses version numbers in their URLs (/v1/, /v2beta/) and maintains multiple versions for years. They provide migration guides and sunset timelines so developers can plan their upgrades.
Salesforce: Salesforce releases new API versions with each product release, numbered sequentially (v50.0, v51.0, etc.). They support many past versions simultaneously, retiring very old ones with plenty of advance notice.
Your Internal APIs: Even if you’re building internal services, versioning matters. When your team updates the user service API, the mobile team shouldn’t have to deploy an emergency update at midnight. Versions let different teams work at their own pace.
Analogy
The Restaurant Menu Evolution: A restaurant might update their menu, but they keep the “classics” section for regulars who come specifically for the original dishes. The chef can innovate with new offerings (v2) while still serving the traditional favorites (v1). Customers aren’t forced to try new dishes if they prefer what they’ve always ordered.
Software Update Channels: Think of how operating systems have “stable” and “beta” channels. You can stay on the stable version (v1) indefinitely while adventurous users test new features in beta (v2). Eventually, beta becomes stable, but you’re never forced to upgrade overnight.
The Highway Expansion: When a city adds new lanes to a highway, they don’t close the existing lanes. Traffic keeps flowing on the old lanes while new ones are built. Once new lanes are ready, drivers can choose to use them. Old lanes might eventually close, but only after everyone has had time to adjust their routes.
Language Dialects: Languages evolve, but old and new forms coexist. Shakespeare’s English and modern English are both “valid” - we don’t stop publishing Shakespeare because language has changed. Similarly, API v1 doesn’t become invalid just because v2 exists. Both serve different needs.
Code Example
// Multiple versioning strategies
GET /v1/products // URI path versioning
GET /v2/products
GET /products?version=2 // Query parameter
GET /products
X-API-Version: 2 // Header-based
GET /products
Accept: application/vnd.company.v2+json // Media type