Projetando e Implementando Estratégias de Versionamento de API com Claude Code

A Importância do Versionamento de API

Breaking changes em APIs têm grande impacto em aplicações cliente. Com o Claude Code, você pode realizar desde o design da estratégia de versionamento até a implementação de forma consistente.

Três Abordagens de Versionamento

Abordagem	Exemplo	Vantagens	Desvantagens
Caminho URL	/api/v1/users	Claro e compreensível	URL muda
Header	API-Version: 1	URL limpa	Difícil de descobrir
Accept	Accept: application/vnd.app.v1+json	Conforme padrão HTTP	Pode ficar complexo

Implementação da Abordagem por Caminho URL

A abordagem mais comum e compreensível.

import express from "express";

const app = express();

// Router por versão
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();
  // Formato de resposta 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 },
  });
  // Formato de resposta v2 (paginação adicionada)
  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,
    },
  });
});

Implementação da Abordagem por 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);

  // Verificar se a versão é suportada
  const supportedVersions = [1, 2, 3];
  if (!supportedVersions.includes(req.apiVersion)) {
    return res.status(400).json({
      error: `Versão da API não suportada: ${version}`,
      supportedVersions,
    });
  }

  // Header de aviso para versões obsoletas
  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);
  }
});

Padrão de Transformação de Resposta

Um design onde as diferenças entre versões são absorvidas por uma camada de transformação.

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

Deprecação e Suporte à Migração

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

    next();
  };
}

// v1 está prevista para ser descontinuada em junho de 2026
app.use(
  "/api/v1",
  deprecationNotice(
    "2026-06-01",
    "https://docs.example.com/migration/v1-to-v2"
  ),
  v1Router
);

Prompts de Implementação para o Claude Code

Exemplos de prompts para introduzir versionamento de API com o Claude Code. Para fundamentos de design de API, consulte o guia introdutório do Claude Code, e para tratamento de erros, consulte design de Error Boundary.

Introduza versionamento na REST API existente.
- Abordagem por caminho URL (/api/v1, /api/v2)
- v1 mantém a API atual sem alterações
- v2 unifica o formato de resposta (adicionar paginação)
- Configure também headers de deprecação para v1
- Crie também documentação de guia de migração

Para melhores práticas de versionamento de API, as Microsoft REST API Guidelines também são uma referência útil. Para informações sobre o uso do Claude Code, consulte a documentação oficial.

Resumo

O versionamento de API é um design indispensável para operação de longo prazo. Ao usar o Claude Code para entender a estrutura do código existente e depois introduzir o versionamento, você pode evoluir a API minimizando o impacto nos clientes existentes.