Mendesain dan Mengimplementasikan Strategi API Versioning dengan Claude Code

Pentingnya API Versioning

Breaking change pada API memberikan dampak besar pada aplikasi client. Dengan Claude Code, desain strategi versioning hingga implementasi bisa dilakukan secara konsisten.

3 Metode Versioning

Metode	Contoh	Kelebihan	Kekurangan
URL Path	/api/v1/users	Jelas dan mudah dipahami	URL berubah
Header	API-Version: 1	URL tetap bersih	Sulit ditemukan
Accept	Accept: application/vnd.app.v1+json	Sesuai standar HTTP	Bisa menjadi kompleks

Implementasi Metode URL Path

Metode yang paling umum dan mudah dipahami.

import express from "express";

const app = express();

// Router per versi
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();
  // Format respons v1
  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 },
  });
  // Format respons v2 (pagination ditambahkan)
  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,
    },
  });
});

Implementasi Metode Header

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);

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

  // Header peringatan versi deprecated
  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);
  }
});

Pola Transformasi Respons

Desain yang menyerap perbedaan antar versi dengan transformation layer.

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 dan Dukungan Migrasi

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 akan di-deprecate pada Juni 2026
app.use(
  "/api/v1",
  deprecationNotice(
    "2026-06-01",
    "https://docs.example.com/migration/v1-to-v2"
  ),
  v1Router
);

Prompt Implementasi dengan Claude Code

Contoh prompt untuk meminta Claude Code memperkenalkan API versioning. Untuk dasar desain API, lihat Panduan Memulai Claude Code, untuk error handling lihat Desain Error Boundary.

Perkenalkan versioning ke REST API yang sudah ada.
- Metode URL path (/api/v1, /api/v2)
- v1 pertahankan API saat ini apa adanya
- v2 unifikasi format respons (tambahkan pagination)
- Set juga header deprecation untuk v1
- Buat juga dokumentasi panduan migrasi

Untuk best practice API versioning, Microsoft REST API Guidelines juga bisa menjadi referensi. Untuk penggunaan Claude Code, periksa Dokumentasi Resmi.

Summary

API versioning adalah desain yang esensial untuk operasi jangka panjang. Dengan memperkenalkan versioning setelah memahami struktur kode yang ada menggunakan Claude Code, kamu bisa mengembangkan API sambil meminimalkan dampak pada client yang sudah ada.