API Versioning

What is it?

📱 Think of it like phone updates:

When Apple releases iOS 18, they don't kill iOS 17 immediately. Millions of older iPhones still run iOS 17. Both versions coexist. Over time, older versions are deprecated (no longer supported).

API Versioning is the same — when you change your API (add fields, rename endpoints, change response format), you don't break ALL existing apps/clients overnight. You release a NEW version (v2) while keeping the OLD version (v1) running. Old apps keep working; new apps use the better version.

Without versioning: you change the API response format on Monday → every mobile app in production crashes because they expect the OLD format → users give 1-star reviews → disaster.

💡 Simple Summary: API versioning lets you evolve your API without breaking existing clients. Old version keeps working while new version adds improvements.

How it works — Like you're watching it happen

The problem API versioning solves:

- Keep /v1/users returning OLD format (user_name, created)

- Launch /v2/users returning NEW format (username, created_at)

- Notify developers: "V1 deprecated, V2 available, V1 shutdown in 6 months"

- Apps migrate at their own pace. No one breaks. ✅

Where to put the version:

❓ But wait — GraphQL claims it doesn't need versioning. How?

GraphQL is additive — you ADD new fields without removing old ones. Old queries that ask for old fields still work. New queries can ask for new fields. Since the client specifies exactly what it wants, adding fields doesn't break anyone. REST can't do this easily because the server decides the response shape. That said, even GraphQL eventually needs to deprecate fields, which is its form of "versioning."

Why should you care? (Interview perspective)

Key Things to Remember

Real Examples You Use Daily

💳 Stripe — Uses date-based versioning (2023-08-16, 2024-01-15). Each API key is pinned to a version. New features require opting into a newer version. You upgrade at your own pace. This is the gold standard.

🐦 Twitter — URL-based: /1.1/tweets/search vs /2/tweets/search. V2 is completely redesigned. V1.1 ran for YEARS after V2 launched.

🗺️ Google Maps — /maps/api/place/v1/... Different versions for different feature sets. Old versions deprecated with clear timelines.

📱 Mobile apps — When Instagram changes their API, they must keep old versions running because millions of phones have OLD app versions that won't update for months. API versioning gives them time.

Common Mistakes in Interviews

❌ Saying "just update the API and tell clients to upgrade" — You CANNOT force millions of mobile apps to update simultaneously. Some users never update! Versioning gives a graceful migration path.

❌ Versioning every minor change — Adding an optional field? NOT a new version. Only version on BREAKING changes. Over-versioning creates maintenance burden.

❌ Not having a deprecation plan — "We'll keep v1 running forever." No! That's unbounded maintenance cost. Set clear sunset dates: "V1 supported until December 2025."

❌ Forgetting about mobile apps — Web apps can update instantly (deploy new frontend). Mobile apps are installed on user devices — old versions persist for months/years. This is the PRIMARY reason API versioning exists.

❌ Making backward-incompatible changes without realizing — Changing a field from string to integer, removing a field "nobody uses" (someone always uses it), or changing error format — all breaking changes that need a new version.

🎯 Interview One-Liner

"I'd version the API in the URL path (/v1, /v2) for discoverability, only bump versions for breaking changes, maintain a clear deprecation policy with Sunset headers, and ensure backward compatibility by adding new fields as optional rather than modifying or removing existing ones."

Interview Q&A