API Versioning and Evolution

# Version 1.0 (original API)
GET /api/users/123
{
"id": 123,
"username": "alice",
"email": "alice@example.com",
"created_at": "2020-01-15"
}

# Mobile app released in January 2020
# Expects "email" field, uses it for password reset

# Version 2.0 (breaking change - June 2020)
# You decide "email" should be "email_address" for clarity

GET /api/users/123
{
"id": 123,
"username": "alice",
"email_address": "alice@example.com",  # ⚠️ Renamed field
"created_at": "2020-01-15"
}

# Result: All mobile apps crash!
# Error: KeyError: 'email'
# Users can't reset passwords
# App Store rating drops from 4.5★ to 2.1★
# 10,000 support tickets in 24 hours

# Version 1 - Keep running for existing clients
GET /api/v1/users/123
{
"id": 123,
"username": "alice",
"email": "alice@example.com",
"created_at": "2020-01-15"
}

# Version 2 - New clients use improved structure
GET /api/v2/users/123
{
"id": 123,
"username": "alice",
"email_address": "alice@example.com",
"created_at": "2020-01-15T10:30:00Z",  # ISO 8601 format
"profile": {
    "bio": "Software engineer",
    "avatar": "https://..."
}
}

# Result:
# ✓ Old mobile apps keep working
# ✓ New clients get improved API
# ✓ Smooth migration over 6-12 months
# ✓ Happy users, happy developers

# Examples
GET https://api.stripe.com/v1/charges
GET https://api.twitter.com/2/tweets
GET https://api.example.com/v1/users

# Patterns
/v1/users          # Major version only
/v2.1/users        # Major.minor version
/2023-10-01/users  # Date-based (Stripe uses this)

# Request with custom header
GET https://api.example.com/users
API-Version: 2
Accept: application/json

# Response
HTTP/1.1 200 OK
API-Version: 2
{
"users": [...]
}

# GitHub uses this approach
GET https://api.github.com/users/octocat
X-GitHub-Api-Version: 2022-11-28

# Examples
GET https://api.example.com/users?version=2
GET https://api.example.com/users?api_version=2.1
GET https://api.example.com/users?v=2

# Can mix with other parameters
GET https://api.example.com/users?version=2&limit=10&offset=20

# Request
GET https://api.example.com/users
Accept: application/vnd.example.v2+json

# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.example.v2+json
{
"users": [...]
}

# GitHub API example
GET https://api.github.com/users/octocat
Accept: application/vnd.github.v3+json

# Semantic Version Format
v2.3.1
│ │ │
│ │ └─ PATCH: Bug fixes, no API changes
│ └─── MINOR: New features, backward compatible
└───── MAJOR: Breaking changes, not backward compatible

# Examples
v1.0.0 → v1.0.1   Bug fix (no breaking changes)
v1.0.1 → v1.1.0   Added new endpoint (backward compatible)
v1.1.0 → v2.0.0   Removed field (breaking change)

# Response from deprecated endpoint
HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Deprecation: true
Link: <https://api.example.com/v2/users>; rel="successor-version"
Warning: 299 - "API v1 will be sunset on 2024-12-31. Please migrate to v2."

{
"users": [...]
}

from fastapi import FastAPI, Response
from datetime import datetime

app = FastAPI()


@app.get("/v1/users")
async def get_users_v1(response: Response):
"""
Deprecated endpoint - use v2 instead.
Sunset date: 2024-12-31
"""
# Add deprecation headers
response.headers["Sunset"] = "Sat, 31 Dec 2024 23:59:59 GMT"
response.headers["Deprecation"] = "true"
response.headers["Link"] = '<https://api.example.com/v2/users>; rel="successor-version"'
response.headers["Warning"] = '299 - "API v1 will be sunset on 2024-12-31. Please migrate to v2."'

# Return data (still works, but deprecated)
return {"users": [...]}


@app.get("/v2/users")
async def get_users_v2():
"""Current version - recommended"""
return {"users": [...]}

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

# Define supported versions
SUPPORTED_VERSIONS = ["1", "2"]
DEFAULT_VERSION = "2"
DEPRECATED_VERSIONS = ["1"]


def get_api_version(api_version: str = Header(default=DEFAULT_VERSION, alias="API-Version")) -> str:
"""
Extract and validate API version from header.
Adds deprecation warnings for old versions.
"""
if api_version not in SUPPORTED_VERSIONS:
    raise HTTPException(
        status_code=400,
        detail=f"Unsupported API version: {api_version}. Supported versions: {SUPPORTED_VERSIONS}"
    )

return api_version


@app.get("/users")
async def get_users(
response: Response,
version: str = Depends(get_api_version)
):
"""
Versioned endpoint - behavior changes based on API-Version header.
"""
# Warn if using deprecated version
if version in DEPRECATED_VERSIONS:
    response.headers["Sunset"] = "Sat, 31 Dec 2024 23:59:59 GMT"
    response.headers["Deprecation"] = "true"

# Return version-specific response
if version == "1":
    return {
        "users": [
            {"id": 1, "name": "Alice", "email": "alice@example.com"}
        ]
    }
elif version == "2":
    return {
        "data": {
            "users": [
                {"id": 1, "username": "alice", "email_address": "alice@example.com"}
            ]
        },
        "meta": {"version": "2", "count": 1}
    }

project/
├── app/
│   ├── main.py                 # FastAPI app entry point
│   ├── v1/
│   │   ├── __init__.py
│   │   ├── routes.py           # v1 endpoints
│   │   └── schemas.py          # v1 Pydantic models
│   ├── v2/
│   │   ├── __init__.py
│   │   ├── routes.py           # v2 endpoints
│   │   └── schemas.py          # v2 Pydantic models
│   └── shared/
│       ├── database.py         # Shared database logic
│       └── auth.py             # Shared authentication
└── tests/
├── test_v1.py
└── test_v2.py

# app/v1/schemas.py
from pydantic import BaseModel


class UserV1(BaseModel):
id: int
name: str
email: str


class CreateUserV1(BaseModel):
name: str
email: str

# app/v1/routes.py
from fastapi import APIRouter, HTTPException
from .schemas import UserV1, CreateUserV1

router = APIRouter(prefix="/v1", tags=["v1"])

# In-memory database (shared across versions)
from app.shared.database import users_db


@router.get("/users/{user_id}", response_model=UserV1)
async def get_user_v1(user_id: int):
"""Get user by ID - v1 format"""
user = users_db.get(user_id)
if not user:
    raise HTTPException(status_code=404, detail="User not found")

return UserV1(
    id=user["id"],
    name=user["username"],  # Map username → name
    email=user["email"]
)


@router.post("/users", response_model=UserV1)
async def create_user_v1(user: CreateUserV1):
"""Create user - v1 format"""
new_id = max(users_db.keys(), default=0) + 1
new_user = {
    "id": new_id,
    "username": user.name,  # Map name → username in db
    "email": user.email
}
users_db[new_id] = new_user

return UserV1(
    id=new_user["id"],
    name=new_user["username"],
    email=new_user["email"]
)

# app/v2/schemas.py
from pydantic import BaseModel
from typing import Optional


class UserV2(BaseModel):
id: int
username: str  # Changed: name → username
email_address: str  # Changed: email → email_address
bio: Optional[str] = None  # New field


class CreateUserV2(BaseModel):
username: str
email_address: str
bio: Optional[str] = None

# app/v2/routes.py
from fastapi import APIRouter, HTTPException
from .schemas import UserV2, CreateUserV2

router = APIRouter(prefix="/v2", tags=["v2"])

from app.shared.database import users_db


@router.get("/users/{user_id}", response_model=UserV2)
async def get_user_v2(user_id: int):
"""Get user by ID - v2 format"""
user = users_db.get(user_id)
if not user:
    raise HTTPException(status_code=404, detail="User not found")

return UserV2(
    id=user["id"],
    username=user["username"],
    email_address=user["email"],
    bio=user.get("bio")
)


@router.post("/users", response_model=UserV2)
async def create_user_v2(user: CreateUserV2):
"""Create user - v2 format"""
new_id = max(users_db.keys(), default=0) + 1
new_user = {
    "id": new_id,
    "username": user.username,
    "email": user.email_address,
    "bio": user.bio
}
users_db[new_id] = new_user

return UserV2(
    id=new_user["id"],
    username=new_user["username"],
    email_address=new_user["email"],
    bio=new_user.get("bio")
)

# app/main.py
from fastapi import FastAPI
from app.v1 import routes as v1_routes
from app.v2 import routes as v2_routes

app = FastAPI(
title="My Versioned API",
description="API with v1 and v2 versions",
version="2.0.0"
)

# Include version routers
app.include_router(v1_routes.router)
app.include_router(v2_routes.router)


@app.get("/")
async def root():
return {
    "message": "Welcome to My API",
    "versions": {
        "v1": {
            "status": "deprecated",
            "sunset_date": "2024-12-31",
            "docs": "/docs#/v1"
        },
        "v2": {
            "status": "stable",
            "docs": "/docs#/v2"
        }
    }
}

# V1 request
curl http://localhost:8000/v1/users/1

# V1 response
{
"id": 1,
"name": "alice",
"email": "alice@example.com"
}


# V2 request
curl http://localhost:8000/v2/users/1

# V2 response
{
"id": 1,
"username": "alice",
"email_address": "alice@example.com",
"bio": null
}

# app/middleware/version_tracking.py
from fastapi import Request
from collections import defaultdict
import logging

logger = logging.getLogger(__name__)

# Track version usage per client
version_metrics = defaultdict(lambda: defaultdict(int))


async def version_tracking_middleware(request: Request, call_next):
    """Track API version usage for deprecation decisions."""
    # Extract version from URL path
    path = request.url.path
    version = "unknown"

    if "/v1/" in path:
        version = "v1"
    elif "/v2/" in path:
        version = "v2"

    # Track client (API key or IP)
    client_id = request.headers.get("X-API-Key", request.client.host)

    # Increment counter
    version_metrics[version][client_id] += 1

    # Log deprecated version usage
    if version == "v1":
        logger.warning(
            f"Deprecated v1 API called by {client_id}: {request.method} {path}"
        )

    response = await call_next(request)

    # Add version info to response headers
    response.headers["X-API-Version"] = version
    response.headers["X-API-Deprecated"] = str(version == "v1").lower()

    return response


# Register middleware
# app.middleware("http")(version_tracking_middleware)

# Example: API Changelog

## v2.0.0 (2024-06-01) - Breaking Changes

### Breaking
- RENAMED: "name" field → "username" in User responses
- RENAMED: "email" field → "email_address" in User responses
- CHANGED: Response wrapper from {"users": [...]} to {"data": {"users": [...]}}

### Added
- NEW FIELD: "bio" (optional) in User responses
- NEW ENDPOINT: GET /v2/users/{id}/activity

### Migration Guide
1. Update field references:
   - response.name       → response.username
   - response.email      → response.email_address

2. Update response parsing:
   - response.users      → response.data.users

3. Timeline:
   - v1 deprecated: 2024-06-01
   - v1 sunset: 2024-12-31
   - Migration support: support@api.example.com