api-versioning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Versioning

API版本控制

Evolve your API without breaking existing clients.

在不影响现有客户端的前提下迭代你的API。

When to Use This Skill

何时使用该方案

Public APIs with external consumers
Mobile apps (can't force updates)
Breaking changes to existing endpoints
Long-term API maintenance

面向外部用户的公开API
移动应用（无法强制用户更新）
对现有端点进行破坏性变更
API的长期维护

Versioning Strategies

版本控制策略

1. URL Path Versioning (Recommended)

1. URL路径版本控制（推荐）

GET /api/v1/users
GET /api/v2/users

Pros: Clear, cacheable, easy to route Cons: URL pollution

GET /api/v1/users
GET /api/v2/users

优点：清晰明了、可缓存、易于路由缺点：URL冗余

2. Header Versioning

2. 请求头版本控制

GET /api/users
Accept: application/vnd.myapp.v2+json

Pros: Clean URLs Cons: Harder to test, not cacheable by URL

GET /api/users
Accept: application/vnd.myapp.v2+json

优点：URL简洁缺点：测试难度高、无法通过URL缓存

3. Query Parameter

3. 查询参数版本控制

GET /api/users?version=2

Pros: Simple Cons: Easy to forget, caching issues

GET /api/users?version=2

优点：简单易实现缺点：容易遗漏、存在缓存问题

TypeScript Implementation

TypeScript实现

Version Router

版本路由

typescript

// version-router.ts
import { Router, Request, Response, NextFunction } from 'express';

type VersionHandler = (req: Request, res: Response, next: NextFunction) => void;

interface VersionedRoute {
  v1?: VersionHandler;
  v2?: VersionHandler;
  v3?: VersionHandler;
  default: VersionHandler;
}

class VersionRouter {
  private router = Router();
  private currentVersion = 'v2';
  private supportedVersions = ['v1', 'v2'];
  private deprecatedVersions = ['v1'];

  constructor() {
    // Add version detection middleware
    this.router.use(this.detectVersion.bind(this));
  }

  private detectVersion(req: Request, res: Response, next: NextFunction) {
    // Extract version from URL path
    const match = req.path.match(/^\/v(\d+)\//);
    if (match) {
      req.apiVersion = `v${match[1]}`;
    } else {
      req.apiVersion = this.currentVersion;
    }

    // Check if version is supported
    if (!this.supportedVersions.includes(req.apiVersion)) {
      return res.status(400).json({
        error: 'Unsupported API version',
        supportedVersions: this.supportedVersions,
      });
    }

    // Add deprecation warning header
    if (this.deprecatedVersions.includes(req.apiVersion)) {
      res.setHeader('Deprecation', 'true');
      res.setHeader('Sunset', '2025-01-01');
      res.setHeader('Link', '</api/v2>; rel="successor-version"');
    }

    next();
  }

  versioned(path: string, handlers: VersionedRoute) {
    this.router.all(path, (req: Request, res: Response, next: NextFunction) => {
      const version = req.apiVersion as keyof VersionedRoute;
      const handler = handlers[version] || handlers.default;
      handler(req, res, next);
    });
  }

  getRouter() {
    return this.router;
  }
}

// Extend Express Request type
declare global {
  namespace Express {
    interface Request {
      apiVersion?: string;
    }
  }
}

export { VersionRouter };

typescript

// version-router.ts
import { Router, Request, Response, NextFunction } from 'express';

type VersionHandler = (req: Request, res: Response, next: NextFunction) => void;

interface VersionedRoute {
  v1?: VersionHandler;
  v2?: VersionHandler;
  v3?: VersionHandler;
  default: VersionHandler;
}

class VersionRouter {
  private router = Router();
  private currentVersion = 'v2';
  private supportedVersions = ['v1', 'v2'];
  private deprecatedVersions = ['v1'];

  constructor() {
    // Add version detection middleware
    this.router.use(this.detectVersion.bind(this));
  }

  private detectVersion(req: Request, res: Response, next: NextFunction) {
    // Extract version from URL path
    const match = req.path.match(/^\/v(\d+)\//);
    if (match) {
      req.apiVersion = `v${match[1]}`;
    } else {
      req.apiVersion = this.currentVersion;
    }

    // Check if version is supported
    if (!this.supportedVersions.includes(req.apiVersion)) {
      return res.status(400).json({
        error: 'Unsupported API version',
        supportedVersions: this.supportedVersions,
      });
    }

    // Add deprecation warning header
    if (this.deprecatedVersions.includes(req.apiVersion)) {
      res.setHeader('Deprecation', 'true');
      res.setHeader('Sunset', '2025-01-01');
      res.setHeader('Link', '</api/v2>; rel="successor-version"');
    }

    next();
  }

  versioned(path: string, handlers: VersionedRoute) {
    this.router.all(path, (req: Request, res: Response, next: NextFunction) => {
      const version = req.apiVersion as keyof VersionedRoute;
      const handler = handlers[version] || handlers.default;
      handler(req, res, next);
    });
  }

  getRouter() {
    return this.router;
  }
}

// Extend Express Request type
declare global {
  namespace Express {
    interface Request {
      apiVersion?: string;
    }
  }
}

export { VersionRouter };

Usage Example

使用示例

typescript

// routes/users.ts
import { VersionRouter } from './version-router';

const versionRouter = new VersionRouter();

// Different implementations per version
versionRouter.versioned('/users', {
  v1: async (req, res) => {
    // V1: Returns flat user object
    const users = await db.users.findMany();
    res.json(users.map(u => ({
      id: u.id,
      name: u.name,
      email: u.email,
    })));
  },
  v2: async (req, res) => {
    // V2: Returns nested structure with metadata
    const users = await db.users.findMany({ include: { profile: true } });
    res.json({
      data: users.map(u => ({
        id: u.id,
        attributes: {
          name: u.name,
          email: u.email,
          profile: u.profile,
        },
      })),
      meta: { total: users.length },
    });
  },
  default: async (req, res) => {
    // Default to latest
    res.redirect(307, `/api/v2${req.path}`);
  },
});

export const userRoutes = versionRouter.getRouter();

typescript

// routes/users.ts
import { VersionRouter } from './version-router';

const versionRouter = new VersionRouter();

// Different implementations per version
versionRouter.versioned('/users', {
  v1: async (req, res) => {
    // V1: Returns flat user object
    const users = await db.users.findMany();
    res.json(users.map(u => ({
      id: u.id,
      name: u.name,
      email: u.email,
    })));
  },
  v2: async (req, res) => {
    // V2: Returns nested structure with metadata
    const users = await db.users.findMany({ include: { profile: true } });
    res.json({
      data: users.map(u => ({
        id: u.id,
        attributes: {
          name: u.name,
          email: u.email,
          profile: u.profile,
        },
      })),
      meta: { total: users.length },
    });
  },
  default: async (req, res) => {
    // Default to latest
    res.redirect(307, `/api/v2${req.path}`);
  },
});

export const userRoutes = versionRouter.getRouter();

Version Middleware (Header-based)

版本中间件（基于请求头）

typescript

// header-version-middleware.ts
function headerVersionMiddleware(req: Request, res: Response, next: NextFunction) {
  const acceptHeader = req.headers.accept || '';
  
  // Parse: application/vnd.myapp.v2+json
  const match = acceptHeader.match(/application\/vnd\.myapp\.v(\d+)\+json/);
  
  if (match) {
    req.apiVersion = `v${match[1]}`;
  } else {
    req.apiVersion = 'v2'; // Default
  }
  
  next();
}

typescript

// header-version-middleware.ts
function headerVersionMiddleware(req: Request, res: Response, next: NextFunction) {
  const acceptHeader = req.headers.accept || '';
  
  // Parse: application/vnd.myapp.v2+json
  const match = acceptHeader.match(/application\/vnd\.myapp\.v(\d+)\+json/);
  
  if (match) {
    req.apiVersion = `v${match[1]}`;
  } else {
    req.apiVersion = 'v2'; // Default
  }
  
  next();
}

Python Implementation

Python实现

python

undefined

python

undefined

version_router.py

from fastapi import APIRouter, Request, HTTPException from fastapi.responses import JSONResponse from typing import Callable, Dict

class VersionedRouter: def init(self): self.router = APIRouter() self.current_version = "v2" self.supported_versions = ["v1", "v2"] self.deprecated_versions = ["v1"]

def versioned_route(
    self,
    path: str,
    methods: list[str],
    handlers: Dict[str, Callable],
):
    async def route_handler(request: Request):
        # Extract version from path
        version = self._extract_version(request.url.path)
        
        if version not in self.supported_versions:
            raise HTTPException(
                status_code=400,
                detail=f"Unsupported version. Supported: {self.supported_versions}"
            )

        handler = handlers.get(version, handlers.get("default"))
        if not handler:
            raise HTTPException(status_code=404)

        response = await handler(request)
        
        # Add deprecation headers
        if version in self.deprecated_versions:
            response.headers["Deprecation"] = "true"
            response.headers["Sunset"] = "2025-01-01"
        
        return response

    for method in methods:
        self.router.add_api_route(path, route_handler, methods=[method])

def _extract_version(self, path: str) -> str:
    import re
    match = re.search(r"/v(\d+)/", path)
    return f"v{match.group(1)}" if match else self.current_version

undefined

from fastapi import APIRouter, Request, HTTPException from fastapi.responses import JSONResponse from typing import Callable, Dict

class VersionedRouter: def init(self): self.router = APIRouter() self.current_version = "v2" self.supported_versions = ["v1", "v2"] self.deprecated_versions = ["v1"]

def versioned_route(
    self,
    path: str,
    methods: list[str],
    handlers: Dict[str, Callable],
):
    async def route_handler(request: Request):
        # Extract version from path
        version = self._extract_version(request.url.path)
        
        if version not in self.supported_versions:
            raise HTTPException(
                status_code=400,
                detail=f"Unsupported version. Supported: {self.supported_versions}"
            )

        handler = handlers.get(version, handlers.get("default"))
        if not handler:
            raise HTTPException(status_code=404)

        response = await handler(request)
        
        # Add deprecation headers
        if version in self.deprecated_versions:
            response.headers["Deprecation"] = "true"
            response.headers["Sunset"] = "2025-01-01"
        
        return response

    for method in methods:
        self.router.add_api_route(path, route_handler, methods=[method])

def _extract_version(self, path: str) -> str:
    import re
    match = re.search(r"/v(\d+)/", path)
    return f"v{match.group(1)}" if match else self.current_version

undefined

FastAPI Usage

FastAPI使用示例

python

undefined

python

undefined

routes/users.py

from version_router import VersionedRouter

router = VersionedRouter()

async def get_users_v1(request: Request): users = await db.users.find_many() return JSONResponse([{"id": u.id, "name": u.name} for u in users])

async def get_users_v2(request: Request): users = await db.users.find_many(include={"profile": True}) return JSONResponse({ "data": [{"id": u.id, "attributes": {"name": u.name}} for u in users], "meta": {"total": len(users)}, })

router.versioned_route( "/users", methods=["GET"], handlers={ "v1": get_users_v1, "v2": get_users_v2, "default": get_users_v2, }, )

undefined

from version_router import VersionedRouter

router = VersionedRouter()

async def get_users_v1(request: Request): users = await db.users.find_many() return JSONResponse([{"id": u.id, "name": u.name} for u in users])

router.versioned_route( "/users", methods=["GET"], handlers={ "v1": get_users_v1, "v2": get_users_v2, "default": get_users_v2, }, )

undefined

Deprecation Workflow

弃用工作流

1. Announce Deprecation

1. 宣布弃用

typescript

// Add to all v1 responses
res.setHeader('Deprecation', 'true');
res.setHeader('Sunset', '2025-06-01T00:00:00Z');
res.setHeader('Link', '</api/v2/docs>; rel="successor-version"');

typescript

// Add to all v1 responses
res.setHeader('Deprecation', 'true');
res.setHeader('Sunset', '2025-06-01T00:00:00Z');
res.setHeader('Link', '</api/v2/docs>; rel="successor-version"');

2. Log Usage

2. 记录使用情况

typescript

// Track v1 usage for migration planning
if (req.apiVersion === 'v1') {
  metrics.increment('api.v1.requests', {
    endpoint: req.path,
    client: req.headers['x-client-id'],
  });
}

typescript

// Track v1 usage for migration planning
if (req.apiVersion === 'v1') {
  metrics.increment('api.v1.requests', {
    endpoint: req.path,
    client: req.headers['x-client-id'],
  });
}

3. Gradual Sunset

3. 逐步停用

typescript

// Phase 1: Warnings (3 months)
// Phase 2: Rate limit v1 (1 month)
if (req.apiVersion === 'v1') {
  await rateLimiter.consume(req.ip, { points: 10 }); // 10x cost
}

// Phase 3: Return 410 Gone
if (req.apiVersion === 'v1' && Date.now() > SUNSET_DATE) {
  return res.status(410).json({
    error: 'API version v1 has been sunset',
    migration: 'https://docs.example.com/v2-migration',
  });
}

typescript

// Phase 1: Warnings (3 months)
// Phase 2: Rate limit v1 (1 month)
if (req.apiVersion === 'v1') {
  await rateLimiter.consume(req.ip, { points: 10 }); // 10x cost
}

// Phase 3: Return 410 Gone
if (req.apiVersion === 'v1' && Date.now() > SUNSET_DATE) {
  return res.status(410).json({
    error: 'API version v1 has been sunset',
    migration: 'https://docs.example.com/v2-migration',
  });
}

Response Format Evolution

响应格式演进

typescript

// V1 Response (flat)
{
  "id": "123",
  "name": "John",
  "email": "john@example.com"
}

// V2 Response (JSON:API style)
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "john@example.com"
    }
  },
  "meta": {
    "version": "v2"
  }
}

typescript

// V1 Response (flat)
{
  "id": "123",
  "name": "John",
  "email": "john@example.com"
}

// V2 Response (JSON:API style)
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "john@example.com"
    }
  },
  "meta": {
    "version": "v2"
  }
}

Best Practices

最佳实践

Support at least 2 versions - Give clients time to migrate
Use semantic versioning - Major version = breaking changes
Document all changes - Changelog per version
Provide migration guides - Help clients upgrade
Monitor version usage - Know when to sunset

至少支持2个版本 - 给客户端足够的迁移时间
使用语义化版本控制 - 主版本变更代表破坏性变更
记录所有变更 - 每个版本对应变更日志
提供迁移指南 - 帮助客户端升级
监控版本使用情况 - 确定何时可以停用旧版本

Common Mistakes

常见错误

Breaking changes without version bump
No deprecation period
Removing versions without notice
Inconsistent versioning across endpoints
Not tracking version usage metrics

进行破坏性变更但未升级版本号
没有设置弃用过渡期
未提前通知就移除版本
不同端点的版本控制不一致
未跟踪版本使用情况指标