{"title":"API Versioning Explained","description":"","content":"# API Versioning Explained\n\nYou ship an API. Developers integrate it. Then requirements change, you need to rename a field, and suddenly you're staring at a choice: break every client currently using your API, or figure out how to evolve without causing chaos.\n\nThis is the API versioning problem, and every team building APIs eventually faces it. The decisions you make here determine whether your API becomes a joy to work with or a maintenance nightmare.\n\n\n> **INFO**\n>\n> APIs are contracts. Versioning is how you evolve contracts without betraying the people who trusted them.\n\n\nCompanies like Stripe, Twilio, and GitHub have spent years refining their versioning approaches. Their strategies differ, but they share one thing in common: a deep respect for backward compatibility and clear communication about changes.\n\nIn this article, we'll explore API versioning in depth. You'll learn when versioning matters, the major strategies and their trade-offs, how to implement each approach, and how industry leaders handle versioning at scale.\n\n---\n\n# Why API Versioning Matters\n\nAPIs are not static. Requirements evolve, you discover better ways to model data, security vulnerabilities require breaking changes, and business needs shift. Without versioning, every change becomes a potential breaking change.\n\nConsider what happens without versioning:\n\n\n```mermaid\nflowchart TD\n subgraph Before[\"Before: API v1\"]\n Req1[\"GET /users/123
Response: {name: 'Alice'}\"]:::primary\n end\n\n subgraph After[\"After: Unversioned Change\"]\n Req2[\"GET /users/123
Response: {first_name: 'Alice', last_name: 'Smith'}\"]:::orange\n end\n\n subgraph Clients[\"Client Impact\"]\n C1[\"Client A
Expects 'name'
BREAKS\"]:::red\n C2[\"Client B
Expects 'name'
BREAKS\"]:::red\n C3[\"Client C
Expects 'name'
BREAKS\"]:::red\n end\n\n Before --> After\n After --> Clients\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe moment you rename `name` to `first_name`, every client parsing that field breaks. Mobile apps crash. Integrations fail. Customer support tickets flood in.\n\nVersioning solves this by letting old clients continue using the old format while new clients adopt the new one.\n\n---\n\n# Breaking vs. Non-Breaking Changes\n\nBefore choosing a versioning strategy, you need to understand what actually requires a new version.\n\n## Non-Breaking Changes (Safe)\n\nThese changes don't require a new version. Well-behaved clients should handle them gracefully.\n\n\n| Change Type | Example | Why It's Safe |\n|-------------|---------|---------------|\n| Add optional field to response | Add `middle_name` to user | Clients ignore unknown fields |\n| Add new endpoint | Add `GET /users/preferences` | Existing endpoints unchanged |\n| Add optional request parameter | Add `?include_metadata=true` | Old requests still work |\n| Add new enum value | Add `status: \"archived\"` | Most clients use default handling |\n| Improve performance | Faster response times | No interface change |\n| Add new error code | New validation message | Clients should handle unknown errors |\n\n\n## Breaking Changes (Require New Version)\n\nThese changes break existing clients and typically require a new API version.\n\n\n| Change Type | Example | Why It Breaks |\n|-------------|---------|---------------|\n| Remove field from response | Remove `name` field | Clients parsing it fail |\n| Rename field | `name` → `full_name` | Same as removal + addition |\n| Change field type | `id: \"123\"` → `id: 123` | Type parsing fails |\n| Change field meaning | `amount` from cents to dollars | Silent data corruption |\n| Remove endpoint | Delete `DELETE /users` | 404 errors |\n| Make optional field required | `email` now required | Old requests rejected |\n| Change authentication | API key → OAuth | Auth fails |\n| Change error format | New error structure | Error handling breaks |\n\n\n## The Gray Areas\n\nSome changes fall in between and require judgment.\n\n**Adding a required field to request body:**\n\n- Breaking for create operations (old requests fail)\n- Can be non-breaking if you provide a sensible default\n\n**Changing field from required to optional:**\n\n- Usually safe, but clients may have validation logic that breaks\n\n**Adding new enum values:**\n\n- Usually safe, but clients with exhaustive switch statements may crash\n\n**Changing pagination defaults:**\n\n- Usually safe, but may cause performance issues for clients expecting old defaults\n\nThe conservative approach: if you're unsure, treat it as breaking.\n\n---\n\n# Versioning Strategies\n\nThere are four main approaches to API versioning. Each has distinct trade-offs.\n\n## Strategy 1: URL Path Versioning\n\nThe version number is part of the URL path.\n\n\n```shell\nhttps://api.example.com/v1/users\nhttps://api.example.com/v2/users\nhttps://api.example.com/v3/users\n```\n\n\n\n```mermaid\nflowchart LR\n Client[\"Client\"]:::rose\n\n subgraph Gateway[\"API Gateway\"]\n Router[\"Version Router\"]:::secondary\n end\n\n subgraph Versions[\"API Versions\"]\n V1[\"/v1/*
Legacy\"]:::primary\n V2[\"/v2/*
Current\"]:::green\n V3[\"/v3/*
Beta\"]:::orange\n end\n\n Client --> Router\n Router --> V1\n Router --> V2\n Router --> V3\n\n classDef rose fill:#f783ac,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\n**Real-world examples:**\n\n\n```shell\nGitHub: https://api.github.com/v3/users\nStripe: https://api.stripe.com/v1/charges\nTwitter: https://api.twitter.com/2/tweets\nTwilio: https://api.twilio.com/2010-04-01/Accounts\n```\n\n\n**Implementation:**\n\n\n```python\n# Flask example\nfrom flask import Flask, Blueprint\n\napp = Flask(__name__)\n\n# v1 blueprint\nv1 = Blueprint('v1', __name__, url_prefix='/v1')\n\n@v1.route('/users/')\ndef get_user_v1(user_id):\n user = fetch_user(user_id)\n return {\n 'name': f\"{user.first_name} {user.last_name}\" # Combined name\n }\n\n# v2 blueprint\nv2 = Blueprint('v2', __name__, url_prefix='/v2')\n\n@v2.route('/users/')\ndef get_user_v2(user_id):\n user = fetch_user(user_id)\n return {\n 'first_name': user.first_name, # Split name\n 'last_name': user.last_name\n }\n\napp.register_blueprint(v1)\napp.register_blueprint(v2)\n```\n\n\n\n| Pros | Cons |\n|------|------|\n| Explicit and visible in URL | URLs change between versions |\n| Easy to test in browser | All-or-nothing versioning |\n| Cache-friendly (different URLs) | Can lead to code duplication |\n| Simple routing logic | Harder to version individual endpoints |\n| Works with all infrastructure | Clients must update URLs to upgrade |\n\n\n**Best for:** Public APIs, major version changes, APIs with external developers\n\n---\n\n## Strategy 2: Header Versioning\n\nThe version is specified in HTTP headers. Two common approaches:\n\n**Accept header (content negotiation):**\n\n\n```shell\nGET /users/123\nAccept: application/vnd.example.v2+json\n```\n\n\n**Custom header:**\n\n\n```shell\nGET /users/123\nX-API-Version: 2\n```\n\n\n\n```mermaid\nflowchart LR\n subgraph Request[\"HTTP Request\"]\n URL[\"GET /users/123\"]:::primary\n Headers[\"Headers:
Accept: application/vnd.api.v2+json
— or —
X-API-Version: 2\"]:::secondary\n end\n\n Server[\"API Server
Parses header
Routes to version\"]:::orange\n\n Response[\"Response
in requested
version format\"]:::green\n\n Request --> Server --> Response\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\n**Real-world examples:**\n\n\n```shell\nGitHub: Accept: application/vnd.github.v3+json\nAzure: api-version header\nShopify: X-Shopify-API-Version: 2024-01\n```\n\n\n**Implementation:**\n\n\n```python\nfrom flask import Flask, request\n\napp = Flask(__name__)\n\ndef get_api_version():\n # Check custom header first\n version = request.headers.get('X-API-Version')\n if version:\n return int(version)\n\n # Check Accept header\n accept = request.headers.get('Accept', '')\n if 'vnd.example.v2' in accept:\n return 2\n if 'vnd.example.v1' in accept:\n return 1\n\n # Default version\n return 2\n\n@app.route('/users/')\ndef get_user(user_id):\n version = get_api_version()\n user = fetch_user(user_id)\n\n if version == 1:\n return {'name': f\"{user.first_name} {user.last_name}\"}\n else:\n return {'first_name': user.first_name, 'last_name': user.last_name}\n```\n\n\n\n| Pros | Cons |\n|------|------|\n| Clean, stable URLs | Hidden (not visible in URL) |\n| Version per-request flexibility | Harder to test in browser |\n| Follows HTTP semantics | Requires header manipulation |\n| Can version individual endpoints | Less discoverable |\n| Same resource, multiple representations | Caching more complex |\n\n\n**Best for:** APIs where URL stability matters, RESTful purists, fine-grained versioning\n\n---\n\n## Strategy 3: Query Parameter Versioning\n\nThe version is a query parameter.\n\n\n```shell\nGET /users/123?version=2\nGET /users/123?v=2\nGET /users/123?api-version=2024-01\n```\n\n\n\n```mermaid\nflowchart LR\n subgraph Requests[\"Query Parameter Versioning\"]\n R1[\"GET /users?v=1\"]:::primary\n R2[\"GET /users?v=2\"]:::secondary\n R3[\"GET /users?v=3\"]:::orange\n end\n\n Server[\"API Server\"]:::purple\n\n R1 --> Server\n R2 --> Server\n R3 --> Server\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef purple fill:#9775fa,stroke:#000,color:#000\n```\n\n\n**Real-world examples:**\n\n\n```shell\nGoogle: ?v=3\nAWS: ?Version=2012-11-05\nAzure: ?api-version=2023-05-01\n```\n\n\n**Implementation:**\n\n\n```python\nfrom flask import Flask, request\n\napp = Flask(__name__)\n\n@app.route('/users/')\ndef get_user(user_id):\n version = request.args.get('v', '2') # Default to v2\n user = fetch_user(user_id)\n\n if version == '1':\n return {'name': f\"{user.first_name} {user.last_name}\"}\n else:\n return {'first_name': user.first_name, 'last_name': user.last_name}\n```\n\n\n\n| Pros | Cons |\n|------|------|\n| Simple to implement | Pollutes query string |\n| Easy to test (modify URL) | Can conflict with other params |\n| Optional with default | Feels less RESTful |\n| Visible in URL | Cache key complexity |\n\n\n**Best for:** Quick implementations, internal APIs, gradual adoption\n\n---\n\n## Strategy 4: Date-Based Versioning\n\nInstead of version numbers, use dates. Clients pin to a specific date and receive behavior as it existed on that date.\n\n\n```shell\nStripe-Version: 2024-06-20\napi-version: 2023-05-01\n/2010-04-01/Accounts\n```\n\n\n\n```mermaid\nflowchart TB\n subgraph Timeline[\"API Changes Timeline\"]\n D1[\"2023-01-15
Initial release\"]:::primary\n D2[\"2023-06-01
Added phone field\"]:::secondary\n D3[\"2023-09-15
Split name field\"]:::orange\n D4[\"2024-01-01
New auth flow\"]:::purple\n D5[\"2024-06-20
Current\"]:::green\n end\n\n D1 --> D2 --> D3 --> D4 --> D5\n\n subgraph Client[\"Client Pinned to 2023-06-01\"]\n Behavior[\"Sees:
• phone field ✓
• name field (not split)
• old auth flow\"]:::secondary\n end\n\n D2 -.-> Client\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef purple fill:#9775fa,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\n**How Stripe implements date-based versioning:**\n\n\n```shell\nRequest:\nPOST /v1/customers\nStripe-Version: 2023-08-16\n\nServer behavior:\n1. Parse the version header\n2. Look up all API changes in the changelog\n3. Apply changes released before 2023-08-16\n4. Ignore changes released after 2023-08-16\n5. Return response in 2023-08-16 format\n\nResult: Client sees consistent behavior until they explicitly upgrade\n```\n\n\n**Implementation concept:**\n\n\n```python\nfrom datetime import date\nfrom flask import Flask, request\n\napp = Flask(__name__)\n\n# Changelog of breaking changes\nCHANGES = [\n {'date': '2023-06-01', 'change': 'split_name', 'description': 'Split name into first_name, last_name'},\n {'date': '2023-09-15', 'change': 'remove_legacy_id', 'description': 'Remove legacy_id field'},\n {'date': '2024-01-01', 'change': 'amount_in_cents', 'description': 'Amount now in cents, not dollars'},\n]\n\ndef get_active_changes(version_date):\n \"\"\"Return changes that should be active for this version date.\"\"\"\n active = set()\n for change in CHANGES:\n if change['date'] <= version_date:\n active.add(change['change'])\n return active\n\n@app.route('/users/')\ndef get_user(user_id):\n version_date = request.headers.get('API-Version', '2024-06-20')\n active_changes = get_active_changes(version_date)\n user = fetch_user(user_id)\n\n response = {}\n\n if 'split_name' in active_changes:\n response['first_name'] = user.first_name\n response['last_name'] = user.last_name\n else:\n response['name'] = f\"{user.first_name} {user.last_name}\"\n\n if 'remove_legacy_id' not in active_changes:\n response['legacy_id'] = user.legacy_id\n\n return response\n```\n\n\n\n| Pros | Cons |\n|------|------|\n| Pinned, predictable behavior | Complex server-side logic |\n| No arbitrary version numbers | Must maintain change timeline |\n| Clear deprecation timeline | Harder to understand what changed |\n| Gradual migration at client pace | Every change needs dating |\n| Self-documenting changelog | Testing all date combinations |\n\n\n**Best for:** Payment APIs (Stripe), enterprise APIs, APIs with strict backward compatibility requirements\n\n---\n\n# Comparison of Strategies\n\n\n| Aspect | URL Path | Header | Query Param | Date-Based |\n|--------|----------|--------|-------------|------------|\n| **Visibility** | High (in URL) | Low (hidden) | Medium | Medium |\n| **Ease of testing** | Easy | Needs tools | Easy | Medium |\n| **Caching** | Simple | Complex | Medium | Complex |\n| **Granularity** | Entire API | Per-request | Per-request | Per-request |\n| **URL stability** | URLs change | Stable | Mostly stable | Stable |\n| **Implementation** | Simple | Medium | Simple | Complex |\n| **Adoption** | Most common | Growing | Less common | Specialized |\n\n\n\n```mermaid\nflowchart TD\n Start[\"Choose Versioning Strategy\"]:::primary\n\n Q1{\"Public API with
external developers?\"}\n Q2{\"Need per-request
version control?\"}\n Q3{\"Strict backward
compatibility?\"}\n Q4{\"URL stability
important?\"}\n\n URL[\"URL Path
/v1/resource\"]:::green\n Header[\"Header
X-API-Version\"]:::secondary\n Query[\"Query Param
?v=1\"]:::orange\n DateBased[\"Date-Based
2024-06-20\"]:::purple\n\n Start --> Q1\n Q1 -->|Yes| Q3\n Q1 -->|No| Q2\n Q2 -->|Yes| Q4\n Q2 -->|No| URL\n Q3 -->|Yes| DateBased\n Q3 -->|No| URL\n Q4 -->|Yes| Header\n Q4 -->|No| Query\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef purple fill:#9775fa,stroke:#000,color:#000\n```\n\n\n---\n\n# Implementation Patterns\n\n## Pattern 1: Version Adapter Layer\n\nKeep your core business logic in one place. Use adapters to transform between versions.\n\n\n```mermaid\nflowchart TB\n subgraph Clients[\"Clients\"]\n C1[\"v1 Client\"]:::rose\n C2[\"v2 Client\"]:::rose\n C3[\"v3 Client\"]:::rose\n end\n\n subgraph Adapters[\"Version Adapters\"]\n A1[\"v1 Adapter
Transform to/from v3\"]:::orange\n A2[\"v2 Adapter
Transform to/from v3\"]:::orange\n A3[\"v3 Adapter
Pass-through\"]:::green\n end\n\n subgraph Core[\"Core Service\"]\n Service[\"Business Logic
(Implements v3 only)\"]:::primary\n end\n\n C1 --> A1\n C2 --> A2\n C3 --> A3\n A1 --> Service\n A2 --> Service\n A3 --> Service\n\n classDef rose fill:#f783ac,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef primary fill:#00ceff,stroke:#000,color:#000\n```\n\n\n**Implementation:**\n\n\n```python\nclass UserService:\n \"\"\"Core service - always implements latest version.\"\"\"\n\n def get_user(self, user_id):\n user = db.get_user(user_id)\n return {\n 'id': user.id,\n 'first_name': user.first_name,\n 'last_name': user.last_name,\n 'email': user.email,\n 'created_at': user.created_at.isoformat()\n }\n\nclass V1Adapter:\n \"\"\"Transforms v3 responses to v1 format.\"\"\"\n\n def __init__(self, service):\n self.service = service\n\n def get_user(self, user_id):\n user = self.service.get_user(user_id)\n return {\n 'id': user['id'],\n 'name': f\"{user['first_name']} {user['last_name']}\", # Combined\n 'email': user['email']\n # Note: created_at not in v1\n }\n\nclass V2Adapter:\n \"\"\"Transforms v3 responses to v2 format.\"\"\"\n\n def __init__(self, service):\n self.service = service\n\n def get_user(self, user_id):\n user = self.service.get_user(user_id)\n return {\n 'id': user['id'],\n 'first_name': user['first_name'],\n 'last_name': user['last_name'],\n 'email': user['email']\n # Note: created_at added in v3\n }\n\n# Router\ndef get_adapter(version):\n service = UserService()\n if version == 1:\n return V1Adapter(service)\n elif version == 2:\n return V2Adapter(service)\n else:\n return service # v3 uses service directly\n```\n\n\n**Benefits:**\n\n- Single source of truth (core service)\n- Easy to add new versions\n- Easy to deprecate old versions (delete adapter)\n- Clear separation of concerns\n\n---\n\n## Pattern 2: Feature Flags for Gradual Rollout\n\nUse feature flags to test new API behavior before committing to a new version.\n\n\n```mermaid\nflowchart LR\n Request[\"API Request\"]:::primary\n\n subgraph Flags[\"Feature Flags\"]\n F1[\"new_response_format: 10%\"]:::orange\n F2[\"v3_auth: internal only\"]:::orange\n F3[\"split_name: beta users\"]:::orange\n end\n\n subgraph Response[\"Response\"]\n Old[\"Old Format\"]:::secondary\n New[\"New Format\"]:::green\n end\n\n Request --> Flags\n Flags -->|90%| Old\n Flags -->|10%| New\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\n**Implementation:**\n\n\n```python\nfrom feature_flags import is_enabled\n\n@app.route('/users/')\ndef get_user(user_id):\n user = fetch_user(user_id)\n\n # Check if user should see new format\n if is_enabled('new_user_format', user_id=user_id):\n return {\n 'first_name': user.first_name,\n 'last_name': user.last_name,\n 'email': user.email\n }\n else:\n return {\n 'name': f\"{user.first_name} {user.last_name}\",\n 'email': user.email\n }\n```\n\n\n**Workflow:**\n\n1. Deploy new format behind feature flag (0%)\n2. Enable for internal testing (internal users only)\n3. Enable for beta users (opt-in)\n4. Gradual rollout (10% → 25% → 50% → 100%)\n5. If issues, instant rollback (set to 0%)\n6. Once stable, make it the new version default\n\n---\n\n## Pattern 3: Deprecation Headers\n\nCommunicate version status through HTTP headers.\n\n\n```shell\nHTTP/1.1 200 OK\nDeprecation: Sun, 01 Jan 2025 00:00:00 GMT\nSunset: Sun, 01 Jul 2025 00:00:00 GMT\nLink: ; rel=\"successor-version\"\n\n{\n \"name\": \"Alice Johnson\",\n ...\n}\n```\n\n\n**Header meanings:**\n\n\n| Header | Purpose | Example |\n|--------|---------|---------|\n| `Deprecation` | When this version was deprecated | `Deprecation: true` or date |\n| `Sunset` | When this version will stop working | `Sunset: Sun, 01 Jul 2025 00:00:00 GMT` |\n| `Link` | Where to find the new version | `Link: ; rel=\"successor-version\"` |\n| `Warning` | Human-readable deprecation message | `Warning: 299 - \"API v1 deprecated\"` |\n\n\n**Implementation:**\n\n\n```python\nfrom datetime import datetime\nfrom flask import Flask, make_response\n\napp = Flask(__name__)\n\nVERSION_INFO = {\n 'v1': {\n 'deprecated': datetime(2024, 1, 1),\n 'sunset': datetime(2025, 7, 1),\n 'successor': '/v2'\n },\n 'v2': {\n 'deprecated': None,\n 'sunset': None,\n 'successor': None\n }\n}\n\ndef add_deprecation_headers(response, version):\n info = VERSION_INFO.get(version)\n if info and info['deprecated']:\n response.headers['Deprecation'] = info['deprecated'].strftime('%a, %d %b %Y %H:%M:%S GMT')\n response.headers['Sunset'] = info['sunset'].strftime('%a, %d %b %Y %H:%M:%S GMT')\n response.headers['Link'] = f\"<{info['successor']}>; rel=\\\"successor-version\\\"\"\n response.headers['Warning'] = f'299 - \"API {version} is deprecated. Please migrate to {info[\"successor\"]}\"'\n return response\n```\n\n\n---\n\n# Migration Strategies\n\n## The Expand-Contract Pattern for APIs\n\nWhen making breaking changes, use a three-phase approach.\n\n\n```mermaid\nflowchart LR\n subgraph Expand[\"Phase 1: Expand\"]\n E1[\"Add new field
Keep old field\"]:::green\n end\n\n subgraph Transition[\"Phase 2: Transition\"]\n T1[\"Return both fields
Accept both in requests
Migrate clients\"]:::orange\n end\n\n subgraph Contract[\"Phase 3: Contract\"]\n C1[\"Remove old field
Only new field remains\"]:::primary\n end\n\n Expand --> Transition --> Contract\n\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef primary fill:#00ceff,stroke:#000,color:#000\n```\n\n\n**Example: Renaming `name` to `first_name` and `last_name`**\n\n**Phase 1 - Expand (add new fields):**\n\n\n```json\n{\n \"name\": \"Alice Johnson\",\n \"first_name\": \"Alice\",\n \"last_name\": \"Johnson\"\n}\n```\n\n\nBoth old and new clients work. Old clients use `name`, new clients use `first_name`/`last_name`.\n\n**Phase 2 - Transition (migrate clients):**\n\n- Monitor which clients still use `name`\n- Reach out to those clients\n- Provide migration guides\n- Set a deadline\n\n**Phase 3 - Contract (remove old field):**\n\n\n```json\n{\n \"first_name\": \"Alice\",\n \"last_name\": \"Johnson\"\n}\n```\n\n\nOnly after all clients have migrated.\n\n---\n\n## Versioning Without Versions\n\nSometimes you can evolve APIs without formal versioning by following strict compatibility rules.\n\n**Rules for version-less evolution:**\n\n1. **Never remove fields** - Mark as deprecated, return null/empty\n2. **Never rename fields** - Add new field, keep old one\n3. **Never change types** - Add new field with new type\n4. **Always add optional fields** - Never make new fields required\n5. **Always accept unknown fields** - Ignore what you don't recognize\n6. **Design for extension** - Use envelopes, allow for metadata\n\n**Example: Adding a field without breaking clients:**\n\n\n```json\n// Before\n{\n \"id\": 123,\n \"name\": \"Alice\"\n}\n\n// After - safe addition\n{\n \"id\": 123,\n \"name\": \"Alice\",\n \"email\": \"alice@example.com\" // New optional field\n}\n```\n\n\nWell-behaved clients ignore unknown fields, so this just works.\n\n---\n\n# Real-World Examples\n\n## Stripe's Date-Based Versioning\n\nStripe is famous for their API versioning approach.\n\n**How it works:**\n\n1. Every Stripe account has a default API version (set when account was created)\n2. Clients can override per-request with `Stripe-Version` header\n3. All API changes are logged with dates\n4. Responses transform based on the requested version\n\n\n```shell\n# Request with specific version\ncurl https://api.stripe.com/v1/customers \\\n -H \"Authorization: Bearer sk_test_...\" \\\n -H \"Stripe-Version: 2023-08-16\"\n\n# Stripe's changelog shows:\n# 2024-04-10: customer.name split into individual_name and company_name\n# 2023-10-16: invoice.total renamed to amount_due\n# 2023-08-16: payment_method.card.brand now lowercase\n```\n\n\n**Key practices from Stripe:**\n\n- Maintain detailed changelog of all changes\n- Give clients 12+ months before sunsetting old versions\n- Provide upgrade guides for each change\n- Allow testing new versions before committing\n- Dashboard shows which version you're using\n\n---\n\n## GitHub's Accept Header Versioning\n\nGitHub uses content negotiation through the Accept header.\n\n\n```shell\n# Request\nGET https://api.github.com/users/octocat\nAccept: application/vnd.github.v3+json\n\n# Can also request specific media types\nAccept: application/vnd.github.v3.raw+json\nAccept: application/vnd.github.v3.html+json\n```\n\n\n**Key practices from GitHub:**\n\n- Major versions in media type (v3)\n- Minor changes via additional media type parameters\n- Default to latest stable version if no header\n- Preview features via special accept headers\n\n\n```shell\n# Access preview feature\nAccept: application/vnd.github.scarlet-witch-preview+json\n```\n\n\n---\n\n## Twilio's URL Path Versioning\n\nTwilio uses dates in the URL path.\n\n\n```shell\nhttps://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages\n```\n\n\n**Key practices from Twilio:**\n\n- Date in URL indicates API generation\n- Major rewrites get new date\n- Backward compatible changes within same date\n- Clear documentation of what changed between versions\n\n---\n\n# Deprecation and Sunset Best Practices\n\n## The Deprecation Lifecycle\n\n\n```mermaid\nstateDiagram-v2\n [*] --> Active: Version released\n\n Active --> Deprecated: Newer version available\n\n Deprecated --> Warning: Migration deadline set\n\n Warning --> Sunset: Deadline passed\n\n Sunset --> Removed: Grace period ended\n\n Removed --> [*]\n\n classDef active fill:#69db7c,stroke:#000,color:#000\n classDef deprecated fill:#ffd43b,stroke:#000,color:#000\n classDef warning fill:#ffa94d,stroke:#000,color:#000\n classDef sunset fill:#ff8787,stroke:#000,color:#000\n\n class Active active\n class Deprecated deprecated\n class Warning warning\n class Sunset sunset\n```\n\n\n## Timeline Recommendations\n\n\n| API Type | Deprecation Notice | Sunset Period | Total Minimum |\n|----------|-------------------|---------------|---------------|\n| Internal API | 2 weeks | 1 month | 6 weeks |\n| Partner API | 3 months | 6 months | 9 months |\n| Public API | 6 months | 12 months | 18 months |\n| Enterprise API | 12 months | 24 months | 36 months |\n\n\n## Communication Checklist\n\nWhen deprecating a version:\n\n1. **Announce** - Blog post, email to developers, changelog entry\n2. **Document** - Migration guide, code examples, FAQ\n3. **Alert** - Deprecation headers in API responses\n4. **Monitor** - Track which clients still use old version\n5. **Reach out** - Contact high-volume users directly\n6. **Remind** - Periodic reminders as deadline approaches\n7. **Sunset** - Return errors after deadline (with helpful message)\n8. **Remove** - Actually remove code (optional, can keep returning errors)\n\n---\n\n# Metrics and Monitoring\n\n## Key Metrics to Track\n\n\n| Metric | What It Tells You | Action Threshold |\n|--------|-------------------|------------------|\n| Traffic by version | Version adoption | Old version > 20% |\n| Error rate by version | Version health | Spike in any version |\n| Latency by version | Performance comparison | Old version slower |\n| New integrations by version | Developer preference | All new on old version |\n| Migration rate | Upgrade progress | Stalled migration |\n\n\n## Version Health Dashboard\n\n\n```mermaid\nflowchart TD\n subgraph Metrics[\"Version Metrics Dashboard\"]\n subgraph Traffic[\"Traffic Distribution\"]\n T1[\"v1: 5%\"]:::red\n T2[\"v2: 25%\"]:::orange\n T3[\"v3: 70%\"]:::green\n end\n\n subgraph Health[\"Health Indicators\"]\n H1[\"v1: 0.5% errors\"]:::secondary\n H2[\"v2: 0.2% errors\"]:::secondary\n H3[\"v3: 0.1% errors\"]:::secondary\n end\n\n subgraph Alerts[\"Active Alerts\"]\n A1[\"v1 sunset in 30 days
5% traffic remaining\"]:::red\n end\n end\n\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n```\n\n\n---\n\n# System Design Interview Tips\n\nWhen API versioning comes up in interviews, demonstrate understanding of these key points:\n\n## 1. Clarify Requirements First\n\n\n| Question | Why It Matters |\n|----------|----------------|\n| Who are the API consumers? | Internal vs external affects approach |\n| How often do you expect breaking changes? | Frequent changes need flexible strategy |\n| What's the support window for old versions? | Affects complexity and maintenance |\n| Are there regulatory requirements? | Some industries require long support windows |\n\n\n## 2. Lead with Backward Compatibility\n\n\n> **INFO**\n>\n> \"Before discussing versioning strategy, I want to emphasize that we should design for backward compatibility. Most changes can be additive, adding new fields and endpoints rather than modifying existing ones. We should only create new versions for truly breaking changes.\"\n\n\n## 3. Recommend Based on Context\n\n\n| Context | Recommendation |\n|---------|----------------|\n| Public API with many integrators | URL path versioning (explicit, discoverable) |\n| Internal microservices | Header versioning (flexibility) |\n| Payment/financial API | Date-based versioning (strict compatibility) |\n| Startup MVP | Start without versioning, add when needed |\n\n\n## 4. Discuss the Full Lifecycle\n\nDon't just talk about how to version. Cover:\n\n- How clients discover versions\n- How to communicate deprecation\n- Migration tooling and guides\n- Monitoring and metrics\n- Sunset process\n\n## 5. Mention Real Examples\n\nReference how industry leaders do it:\n\n- \"Stripe uses date-based versioning which pins behavior to specific dates...\"\n- \"GitHub uses Accept header versioning for clean URLs...\"\n- \"Most public APIs like Twitter use URL path versioning for discoverability...\"\n\n---\n\n# Summary\n\n\n```mermaid\nflowchart TD\n Title[\"API Versioning\"]:::primary\n\n subgraph Strategies[\"Four Main Strategies\"]\n URL[\"URL Path
/v1/users\"]:::secondary\n Header[\"Header
X-API-Version: 2\"]:::secondary\n Query[\"Query Param
?v=2\"]:::secondary\n Date[\"Date-Based
2024-06-20\"]:::secondary\n end\n\n subgraph Principles[\"Key Principles\"]\n P1[\"Backward compatibility first\"]:::orange\n P2[\"Additive changes when possible\"]:::orange\n P3[\"Clear deprecation timeline\"]:::orange\n P4[\"Monitor version usage\"]:::orange\n end\n\n subgraph Patterns[\"Implementation Patterns\"]\n Pa1[\"Version adapters\"]:::green\n Pa2[\"Feature flags\"]:::green\n Pa3[\"Expand-contract\"]:::green\n Pa4[\"Deprecation headers\"]:::green\n end\n\n Title --> Strategies\n Strategies --> Principles\n Principles --> Patterns\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef secondary fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\n**Key Takeaways:**\n\n1. **Prefer backward compatibility over new versions.** Additive changes (new fields, new endpoints) don't require versions. Only create new versions for truly breaking changes.\n\n1. **URL path versioning is the most common and pragmatic choice** for public APIs. It's explicit, discoverable, and works with all infrastructure.\n\n1. **Date-based versioning provides the strongest backward compatibility** but requires significant implementation complexity. Use it for payment APIs or when strict compatibility is critical.\n\n1. **Plan the full version lifecycle** from creation to sunset. Every version needs clear deprecation timelines and migration paths.\n\n1. **Monitor version usage** to understand when it's safe to deprecate old versions and to catch migration stalls early.\n\n1. **Communicate proactively.** Developers hate surprises. Announce deprecations early, provide migration guides, and reach out to high-volume users.\n\n---\n\n## References\n\n- [Stripe API Versioning](undefined) - The gold standard for date-based API versioning\n- [GitHub REST API Versioning](undefined) - Accept header versioning in practice\n- [Microsoft REST API Guidelines](undefined) - Comprehensive enterprise API versioning guidance\n- [Semantic Versioning](undefined) - The SemVer specification for version numbering\n- [API Deprecation RFC](undefined) - Proposed standard for deprecation headers\n- [Roy Fielding's REST Dissertation](undefined) - Original REST architectural style definition","pageType":"system-design"}

API Versioning Explained

Ashish Pratap Singh

Get Premium