API Versioning

Implement API versioning strategy

Implement API versioning for backward compatibility.

Instructions

Choose a versioning strategy:

URL Path Versioning (recommended)

/api/v1/users    → original
/api/v2/users    → new format

// app/api/v1/users/route.ts
export async function GET() {
  const users = await getUsers();
  return Response.json(users.map(u => ({ id: u.id, name: u.name }))); // v1 shape
}

// app/api/v2/users/route.ts
export async function GET() {
  const users = await getUsers();
  return Response.json(users.map(u => ({
    id: u.id,
    fullName: u.name,      // renamed field
    email: u.email,        // new field
    avatarUrl: u.avatar,   // new field
  })));
}

Header Versioning (alternative)

export async function GET(req: Request) {
  const version = req.headers.get('X-API-Version') ?? '1';
  if (version === '2') return formatV2(data);
  return formatV1(data);
}

Migration Rules

• Never remove fields from an existing version — only add
• Deprecation timeline: announce → 6 months → sunset
• Default to latest stable version for new clients
• Document breaking changes between versions