Claude Code के साथ API Versioning Strategies Design और Implement करें

API Versioning की Importance

API में breaking changes client applications पर बड़ा impact डालते हैं। Claude Code का उपयोग करके, versioning strategy की design से implementation तक consistently किया जा सकता है।

3 Versioning Methods

Method	Example	Advantage	Disadvantage
URL Path	/api/v1/users	Clear और समझने में आसान	URL बदल जाता है
Header	API-Version: 1	URL clean रहता है	Discover करना मुश्किल
Accept	Accept: application/vnd.app.v1+json	HTTP standard compliant	Complex हो सकता है

URL Path Method Implementation

सबसे common और समझने में आसान method है।

import express from "express";

const app = express();

// Version-wise routers
import v1Router from "./routes/v1";
import v2Router from "./routes/v2";

app.use("/api/v1", v1Router);
app.use("/api/v2", v2Router);

// routes/v1/users.ts
const v1Router = express.Router();

v1Router.get("/users", async (req, res) => {
  const users = await prisma.user.findMany();
  // v1 response format
  res.json({
    data: users.map((u) => ({
      id: u.id,
      name: u.name,
      email: u.email,
    })),
  });
});

// routes/v2/users.ts
const v2Router = express.Router();

v2Router.get("/users", async (req, res) => {
  const users = await prisma.user.findMany({
    include: { profile: true },
  });
  // v2 response format (pagination added)
  res.json({
    data: users.map((u) => ({
      id: u.id,
      fullName: u.name,
      email: u.email,
      profile: u.profile,
    })),
    pagination: {
      total: users.length,
      page: 1,
      perPage: 20,
    },
  });
});

Header Method Implementation

function versionMiddleware(
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
) {
  const version = req.headers["api-version"] || "1";
  req.apiVersion = parseInt(version as string, 10);

  // Supported version check
  const supportedVersions = [1, 2, 3];
  if (!supportedVersions.includes(req.apiVersion)) {
    return res.status(400).json({
      error: `Unsupported API version: ${version}`,
      supportedVersions,
    });
  }

  // Deprecated version warning header
  if (req.apiVersion < 2) {
    res.set("Deprecation", "true");
    res.set("Sunset", "2026-06-01");
    res.set(
      "Link",
      '<https://api.example.com/docs/migration>; rel="deprecation"'
    );
  }

  next();
}

app.use("/api", versionMiddleware);

app.get("/api/users", async (req, res) => {
  switch (req.apiVersion) {
    case 1:
      return handleUsersV1(req, res);
    case 2:
      return handleUsersV2(req, res);
    default:
      return handleUsersV2(req, res);
  }
});

Response Transformation Pattern

Version differences को transformation layer से absorb करने वाला design।

type UserV1 = {
  id: string;
  name: string;
  email: string;
};

type UserV2 = {
  id: string;
  fullName: string;
  emailAddress: string;
  createdAt: string;
};

const transformers = {
  1: (user: DBUser): UserV1 => ({
    id: user.id,
    name: user.name,
    email: user.email,
  }),
  2: (user: DBUser): UserV2 => ({
    id: user.id,
    fullName: user.name,
    emailAddress: user.email,
    createdAt: user.createdAt.toISOString(),
  }),
};

function createVersionedHandler<T>(
  fetcher: (req: express.Request) => Promise<T[]>,
  transformerMap: Record<number, (item: T) => unknown>
) {
  return async (req: express.Request, res: express.Response) => {
    const data = await fetcher(req);
    const transform = transformerMap[req.apiVersion];
    res.json({ data: data.map(transform) });
  };
}

Deprecation और Migration Support

function deprecationNotice(
  sunsetDate: string,
  migrationGuide: string
) {
  return (
    req: express.Request,
    res: express.Response,
    next: express.NextFunction
  ) => {
    res.set("Deprecation", "true");
    res.set("Sunset", sunsetDate);
    res.set("Link", `<${migrationGuide}>; rel="deprecation"`);

    console.warn(
      `Deprecated API v${req.apiVersion} accessed: ${req.path}`
    );

    next();
  };
}

// v1 June 2026 में deprecate होगा
app.use(
  "/api/v1",
  deprecationNotice(
    "2026-06-01",
    "https://docs.example.com/migration/v1-to-v2"
  ),
  v1Router
);

Claude Code से Implementation Prompt

API versioning introduce करने के लिए Claude Code को request करने का prompt example। API design basics के लिए Claude Code Getting Started Guide, error handling के लिए Error Boundary Design भी reference करें।

Existing REST API में versioning introduce करो।
- URL path method (/api/v1, /api/v2)
- v1 current API को as-is maintain करो
- v2 में response format unify करो (pagination add करो)
- v1 के deprecation headers भी set करो
- Migration guide documentation भी बनाओ

API versioning best practices के लिए Microsoft REST API Guidelines भी reference हो सकता है। Claude Code के usage के लिए Official Documentation check करें।

Summary

API versioning long-term operation के लिए essential design है। Claude Code से existing code structure समझकर versioning introduce करने पर existing clients पर impact minimize करते हुए evolve किया जा सकता है।