API Versioning Patterns

Evolve your API confidently. Version correctly, deprecate gracefully, migrate safely — without breaking existing consumers.

Versioning Strategies

Pick one strategy and apply it consistently across your entire API surface.

/api/v1/users

/api/users?v=1

Accept-Version: v1

Accept: application/vnd.api.v1+json

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install 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

undefined

"id": 123

"id": "123"

404

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:

routes:
  - match: /api/v1/*
    upstream: api-v1-service:8080
  - match: /api/v2/*
    upstream: api-v2-service:8080

Multi-Version Support

Architecture:

Request → API Gateway → Version Router → v1 Handler → Shared Service Layer → DB
                                        → v2 Handler ↗

Principles:

1. Business logic is version-agnostic. Services, repositories, and domain models are shared.
2. Serialization is version-specific. Each version has its own request validators and response serializers.
3. Transformations are explicit. A

   v1_to_v2

   transformer documents every field mapping.
4. Tests cover all active versions. Every supported version has its own integration test suite.

Maximum concurrent versions: 2–3 active (current + 1–2 deprecated). More than 3 creates unsustainable maintenance burden.

Client Communication

Changelog

Publish a changelog for every release, tagged by version and change type:

## v2.3.0 — 2025-02-01
### Added
- `avatar_url` field on User response
- `GET /api/v2/users/{id}/activity` endpoint
### Deprecated
- `name` field on User — use `first_name` and `last_name` (removal in v3)

Migration Guides

For every major version bump, provide:

• Field-by-field mapping table (v1 → v2)
• Before/after request and response examples
• Code snippets for common languages/SDKs
• Timeline with key dates (announcement, sunset, removal)

SDK Versioning

Align SDK major versions with API major versions:

api-client@1.x  →  /api/v1
api-client@2.x  →  /api/v2

Ship the new SDK before announcing API deprecation.

Anti-Patterns

NEVER Do

1. NEVER remove a field, endpoint, or change a type without bumping the major version
2. NEVER sunset a public API version with less than 6 months notice
3. NEVER mix versioning strategies in the same API (URL path for some, headers for others)
4. NEVER use minor or patch versions in URL paths (

   /api/v1.2/

   is wrong — use

   /api/v1/

   )
5. NEVER version individual endpoints independently — version the entire API surface as a unit
6. NEVER deploy a breaking change under an existing version number, even if "nobody uses that field"
7. NEVER skip documenting differences between versions — every breaking change needs a migration guide entry