API バージョニング戦略

目次

• 概要
• 使用時期
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

REST API、GraphQL、gRPCサービスのAPIバージョニングアプローチ、非推奨化戦略、後方互換性技術、マイグレーション計画に関する包括的ガイド。

使用時期

• 最初からバージョニングを含めた新しいAPIを設計する場合
• 既存のAPIに破壊的変更を追加する場合
• 古いAPIバージョンを非推奨にする場合
• APIマイグレーションを計画する場合
• 後方互換性を確保する場合
• 複数のAPIバージョンを同時に管理する場合
• 異なるバージョン向けのAPIドキュメントを作成する場合
• APIバージョンルーティングを実装する場合

クイックスタート

最小限の動作例：

// express-router.ts
import express from "express";

const app = express();

// バージョン1
app.get("/api/v1/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe" }],
  });
});

// バージョン2 - emailフィールドを追加
app.get("/api/v2/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe", email: "john@example.com" }],
  });
});

// バージョン固有の変換を含む共通ロジック
app.get("/api/:version/users/:id", async (req, res) => {
  const user = await userService.findById(req.params.id);

  if (req.params.version === "v1") {
    res.json({ id: user.id, name: user.name });
// ... (完全な実装についてはリファレンスガイドを参照)

リファレンスガイド

references/ ディレクトリの詳細な実装：

ベストプラクティス

✅ すべき こと

• 初日からバージョニングを行う（v1でも）
• 破壊的変更と非破壊的変更を文書化する
• コード例を含めた明確なマイグレーションガイドを提供する
• セマンティックバージョニングの原則を使用する
• 6～12ヶ月の非推奨化通知期間を設ける
• 非推奨APIの使用状況を監視する
• APIコンシューマーに非推奨警告を送信する
• 少なくとも2つのバージョンを同時にサポートする
• バージョロジック用にアダプタ/トランスフォーマーを使用する
• サポートするすべてのバージョンをテストする
• どのAPIバージョンが使用されているかをログに記録する
• 可能な場合はマイグレーションツールを提供する
• バージョニングアプローチの一貫性を保つ

❌ してはいけない こと

• バージョニングなしでAPI動作を変更する
• 通知なしでバージョンを削除する
• 多すぎるバージョンをサポートする（3つ以上）
• 同じAPI内で異なるバージョニング戦略を使用する
• バージョンをインクリメントしてAPIを破壊する
• ドキュメント更新を忘れる
• 非推奨化が早すぎる（6ヶ月未満）
• APIコンシューマーのフィードバックを無視する
• すべての変更を新しいバージョンにする
• バージョン番号の使用に一貫性がない