Api Versioning

URL Path Versioning

The most common strategy. Version lives in the URL, making it immediately visible.

from fastapi import FastAPI, APIRouter

v1 = APIRouter(prefix="/api/v1")
v2 = APIRouter(prefix="/api/v2")

@v1.get("/users")
async def list_users_v1():
    return {"users": [...]}

@v2.get("/users")
async def list_users_v2():
    return {"data": {"users": [...]}, "meta": {...}}

app = FastAPI()
app.include_router(v1)
app.include_router(v2)

Rules:

• Always prefix: /api/v1/... not /v1/api/...
• Major version only: /api/v1/, never /api/v1.2/ or /api/v1.2.3/
• Every endpoint must be versioned — no mixing versioned and unversioned paths

Header Versioning

Version specified via request headers, keeping URLs clean.

function versionRouter(req, res, next) {
  const version = req.headers['accept-version'] || 'v2'; // default to latest
  req.apiVersion = version;
  next();
}

app.get('/api/users', versionRouter, (req, res) => {
  if (req.apiVersion === 'v1') return res.json({ users: [...] });
  if (req.apiVersion === 'v2') return res.json({ data: { users: [...] }, meta: {} });
  return res.status(400).json({ error: `Unsupported version: ${req.apiVersion}` });
});

Always define fallback behavior when no version header is sent — default to latest stable or return 400 Bad Request.

Semantic Versioning for APIs

Only MAJOR versions appear in URL paths. Communicate MINOR and PATCH through changelogs.

Breaking vs Non-Breaking Changes

Breaking — Require New Version

Non-Breaking — Safe Under Same Version

Deprecation Strategy

Never remove a version without warning. Follow this timeline:

Phase 1: ANNOUNCE
  • Sunset header on responses  • Changelog entry
  • Email/webhook to consumers  • Docs marked "deprecated"

Phase 2: SUNSET PERIOD
  • v1 still works but warns     • Monitor v1 traffic
  • Contact remaining consumers  • Provide migration support

Phase 3: REMOVAL
  • v1 returns 410 Gone
  • Response body includes migration guide URL
  • Redirect docs to v2

Minimum deprecation periods: Public API: 12 months · Partner API: 6 months · Internal API: 1–3 months

Sunset HTTP Header (RFC 8594)

Include on every response from a deprecated version:

HTTP/1.1 200 OK
Sunset: Sat, 01 Mar 2025 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/docs/migrate-v1-v2>; rel="sunset"
X-API-Warn: "v1 is deprecated. Migrate to v2 by 2025-03-01."

Retired Version Response

When past sunset, return 410 Gone:

{
  "error": "VersionRetired",
  "message": "API v1 was retired on 2025-03-01.",
  "migration_guide": "https://api.example.com/docs/migrate-v1-v2",
  "current_version": "v2"
}

Migration Patterns

Adapter Pattern

Shared business logic, version-specific serialization:

class UserService:
    async def get_user(self, user_id: str) -> User:
        return await self.repo.find(user_id)

def to_v1(user: User) -> dict:
    return {"id": user.id, "name": user.full_name, "email": user.email}

def to_v2(user: User) -> dict:
    return {
        "id": user.id,
        "name": {"first": user.first_name, "last": user.last_name},
        "emails": [{"address": e, "primary": i == 0} for i, e in enumerate(user.emails)],
        "created_at": user.created_at.isoformat(),
    }

Facade Pattern

Single entry point delegates to the correct versioned handler:

async def get_user(user_id: str, version: int):
    user = await user_service.get_user(user_id)
    serializers = {1: to_v1, 2: to_v2}
    serialize = serializers.get(version)
    if not serialize:
        raise UnsupportedVersionError(version)
    return serialize(user)

Versioned Controllers

Separate controller files per version, shared service layer:

api/
  v1/
    users.py      # v1 request/response shapes
    orders.py
  v2/
    users.py      # v2 request/response shapes
    orders.py
  services/
    user_service.py   # version-agnostic business logic
    order_service.py

API Gateway Routing

Route versions at infrastructure layer: