api-versioning-strategy

API のバージョニング戦略

目次

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

概要

REST API、GraphQL、gRPC サービス向けの API バージョニング手法、非推奨化戦略、後方互換性を保つテクニック、移行計画を網羅したガイドです。

使用する場面

• 最初からバージョニングを考慮して新しい API を設計する場合
• 既存の API に破壊的変更を加える場合
• 古い API バージョンを非推奨にする場合
• API の移行を計画する場合
• 後方互換性を確保する場合
• 複数の API バージョンを同時に管理する場合
• バージョンごとの API ドキュメントを作成する場合
• API のバージョンルーティングを実装する場合

クイックスタート

最小限の動作例：

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

const app = express();

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

// Version 2 - Added email field
app.get("/api/v2/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe", email: "[email protected]" }],
  });
});

// Shared logic with version-specific transformations
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 });
// ... (see reference guides for full implementation)

リファレンスガイド

詳しい実装については、references/ ディレクトリを参照してください。

ガイド	内容
バージョニング手法	バージョニング手法
後方互換性のパターン	後方互換性のパターン
非推奨化戦略	非推奨化戦略
移行ガイドの例	移行ガイドの例
レスポンス構造	レスポンス構造
日付形式	日付形式、エラー形式
JavaScript/TypeScript	JavaScript/TypeScript、Python
GraphQL のバージョニング	GraphQL のバージョニング
gRPC のバージョニング	gRPC のバージョニング
バージョンの検出とルーティング	バージョンの検出とルーティング
複数バージョンのテスト	複数バージョンのテスト
パターン 1：バージョン非依存のコア	パターン 1：バージョン非依存のコア、パターン 2：段階的なロールアウトのための機能フラグ、パターン 3：API バージョンのメトリクス

ベストプラクティス

✅ 推奨事項

• 初日からバージョニングを行う（v1 のみの場合でも）
• 破壊的変更と非破壊的変更を明記する
• コード例を含む、わかりやすい移行ガイドを提供する
• セマンティックバージョニングの原則を使う
• 非推奨化を 6～12 か月前に通知する
• 非推奨の API の使用状況を監視する
• API の利用者に非推奨化の警告を送る
• 少なくとも 2 つのバージョンを同時にサポートする
• バージョンロジックにアダプターや変換処理を使う
• サポート対象のすべてのバージョンをテストする
• 使用中の API バージョンを記録する
• 可能な場合は移行ツールを提供する
• バージョニング手法に一貫性を持たせる

❌ 避けるべきこと

• バージョニングせずに API の動作を変更する
• 通知なしにバージョンを削除する
• 多すぎるバージョンをサポートする（3 を超える）
• 同じ API で異なるバージョニング戦略を使う
• バージョンを上げずに API に破壊的変更を加える
• ドキュメントの更新を忘れる
• 非推奨化を急ぎすぎる（6 か月未満）
• API 利用者からのフィードバックを無視する
• 変更のたびに新しいバージョンを作る
• バージョン番号の付け方に一貫性を欠く