API-Versionierungsstrategien mit Claude Code entwerfen und implementieren

Die Bedeutung der API-Versionierung

Breaking Changes an APIs haben große Auswirkungen auf Client-Anwendungen. Mit Claude Code können Sie vom Design der Versionierungsstrategie bis zur Implementierung alles konsistent durchführen.

Drei Versionierungsansätze

Ansatz	Beispiel	Vorteile	Nachteile
URL-Pfad	/api/v1/users	Klar und verständlich	URL ändert sich
Header	API-Version: 1	URL bleibt sauber	Schwer zu entdecken
Accept	Accept: application/vnd.app.v1+json	HTTP-Standard-konform	Kann komplex werden

Implementierung des URL-Pfad-Ansatzes

Der gebräuchlichste und verständlichste Ansatz.

import express from "express";

const app = express();

// Router pro Version
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-Antwortformat
  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-Antwortformat (Paginierung hinzugefügt)
  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,
    },
  });
});

Implementierung des Header-Ansatzes

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

  // Prüfen, ob die Version unterstützt wird
  const supportedVersions = [1, 2, 3];
  if (!supportedVersions.includes(req.apiVersion)) {
    return res.status(400).json({
      error: `Nicht unterstützte API-Version: ${version}`,
      supportedVersions,
    });
  }

  // Warnheader für veraltete Versionen
  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-Transformations-Pattern

Ein Design, bei dem Unterschiede zwischen Versionen durch eine Transformationsschicht aufgefangen werden.

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 und Migrationsunterstützung

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(
      `Veraltete API v${req.apiVersion} aufgerufen: ${req.path}`
    );

    next();
  };
}

// v1 wird voraussichtlich im Juni 2026 eingestellt
app.use(
  "/api/v1",
  deprecationNotice(
    "2026-06-01",
    "https://docs.example.com/migration/v1-to-v2"
  ),
  v1Router
);

Implementierungs-Prompts für Claude Code

Beispiel-Prompts für die Einführung der API-Versionierung mit Claude Code. API-Design-Grundlagen finden Sie im Claude Code Einführungsleitfaden, Fehlerbehandlung unter Error-Boundary-Design.

Führe Versionierung für die bestehende REST API ein.
- URL-Pfad-Ansatz (/api/v1, /api/v2)
- v1 behält die aktuelle API unverändert bei
- v2 vereinheitlicht das Antwortformat (Paginierung hinzufügen)
- Setze auch Deprecation-Header für v1
- Erstelle auch Migrationsleitfaden-Dokumentation

Für Best Practices zur API-Versionierung sind auch die Microsoft REST API Guidelines hilfreich. Informationen zur Nutzung von Claude Code finden Sie in der offiziellen Dokumentation.

Zusammenfassung

API-Versionierung ist ein unverzichtbares Design für den Langzeitbetrieb. Wenn Sie mit Claude Code die Struktur des bestehenden Codes verstehen und dann Versionierung einführen, können Sie die API weiterentwickeln und gleichzeitig die Auswirkungen auf bestehende Clients minimieren.