API Versioning: Strategier för bakåtkompatibla API-ändringar

// De tre vanligaste versioning-strategierna

// 1. URL-versioning (vanligast, enklast)
GET /api/v1/products
GET /api/v2/products

// 2. Header-versioning (renare URL:er)
GET /api/products
Accept: application/vnd.myapi.v2+json

// 3. Query parameter (enklast att testa)
GET /api/products?version=2

// Express.js: URL-versioning med separata routers
import express from "express";
import v1Router from "./routes/v1";
import v2Router from "./routes/v2";

const app = express();

// Varje version har sin egen router
app.use("/api/v1", v1Router);
app.use("/api/v2", v2Router);

// routes/v1/products.ts - Originalformat
router.get("/products", async (req, res) => {
  const products = await db.products.findMany();
  res.json({
    data: products.map((p) => ({
      id: p.id,
      name: p.name,
      price: p.price,
    })),
  });
});

// routes/v2/products.ts - Nytt format med extra fält
router.get("/products", async (req, res) => {
  const products = await db.products.findMany({
    include: { category: true, variants: true },
  });
  res.json({
    data: products.map((p) => ({
      id: p.id,
      name: p.name,
      pricing: {
        amount: p.price,
        currency: p.currency,
        formatted: `${p.price} ${p.currency}`,
      },
      category: p.category.name,
      variantCount: p.variants.length,
    })),
    meta: { version: "v2", count: products.length },
  });
});

// Header-versioning middleware
function versionMiddleware(req, res, next) {
  // Prioritetsordning: custom header > accept header > default
  const customVersion = req.headers["x-api-version"];
  const acceptHeader = req.headers.accept || "";

  // Parsa version från Accept header
  // Format: application/vnd.myapi.v2+json
  const acceptMatch = acceptHeader.match(
    /application\/vnd\.myapi\.v(\d+)\+json/
  );

  if (customVersion) {
    req.apiVersion = parseInt(customVersion, 10);
  } else if (acceptMatch) {
    req.apiVersion = parseInt(acceptMatch[1], 10);
  } else {
    req.apiVersion = 2; // Senaste stabila version
  }

  // Avvisa okända versioner
  const SUPPORTED_VERSIONS = [1, 2, 3];
  if (!SUPPORTED_VERSIONS.includes(req.apiVersion)) {
    return res.status(400).json({
      error: "unsupported_version",
      message: `API version ${req.apiVersion} stöds inte`,
      supported: SUPPORTED_VERSIONS,
    });
  }

  // Varna för deprecated versioner
  if (req.apiVersion === 1) {
    res.setHeader("Deprecation", "true");
    res.setHeader("Sunset", "2026-09-01");
    res.setHeader(
      "Link",
      '</api/v2/docs>; rel="successor-version"'
    );
  }

  next();
}

// Använd i route handler
router.get("/products", versionMiddleware, async (req, res) => {
  if (req.apiVersion === 1) {
    return respondV1(req, res);
  }
  return respondV2(req, res);
});

// Deprecation-strategi med automatisk notifiering

interface VersionConfig {
  version: number;
  status: "current" | "deprecated" | "retired";
  sunsetDate?: Date;
}

const VERSION_CONFIG: VersionConfig[] = [
  { version: 1, status: "deprecated", sunsetDate: new Date("2026-09-01") },
  { version: 2, status: "current" },
  { version: 3, status: "current" },  // Beta
];

// Middleware som loggar deprecated version-anrop
async function deprecationTracker(req, res, next) {
  const config = VERSION_CONFIG.find(
    (v) => v.version === req.apiVersion
  );

  if (config?.status === "retired") {
    return res.status(410).json({
      error: "version_retired",
      message: `API v${req.apiVersion} är nedlagd`,
      migration: `Se /docs/migration/v${req.apiVersion + 1}`,
    });
  }

  if (config?.status === "deprecated") {
    // Logga för uppföljning
    await db.deprecationLog.create({
      data: {
        apiKey: req.apiKeyRecord?.prefix || "unknown",
        version: req.apiVersion,
        endpoint: req.path,
        timestamp: new Date(),
      },
    });
  }

  next();
}

// Veckovis rapport: vilka klienter använder deprecated versioner?
async function generateMigrationReport() {
  const usage = await db.deprecationLog.groupBy({
    by: ["apiKey"],
    _count: { apiKey: true },
    where: {
      timestamp: { gte: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) },
    },
    orderBy: { _count: { apiKey: "desc" } },
  });

  return usage.map((u) => ({
    client: u.apiKey,
    requestsLastWeek: u._count.apiKey,
  }));
}