SaaS APIの「破壊的変更」を防ぐバージョニング戦略と実装パターン

はじめに

エンジニアとしてAPIを設計していると、「機能追加やリファクタリングを行いたいけれど、既存のクライアントを壊したくない」というジレンマに直面することがあります。特にSaaS製品において、APIは製品と外部世界をつなぐ重要な契約です。一度公開したAPIを勝手に変更すれば、連携しているパートナーや顧客のシステムが停止し、信頼を失うことになりかねません。

私自身、過去にフィールド名の型変更を行ったことで、特定のクライアントでパースエラーが連発し、急遽ロールバックを行った苦い経験があります。この教訓から、APIの進化をいかに安全に行うかは、単なる技術的な課題ではなく、製品の持続可能性を左右するビジネス課題だと認識しています。

本記事では、SaaS APIの「破壊的変更」を防ぎ、製品を進化させ続けるためのバージョニング戦略について、理論的な背景から実装レベルの詳細まで解説します。

APIバージョニングとは？

APIバージョニングとは、APIの仕様に変更が生じた際、新旧の仕様を共存させ、クライアントが移行するまでの期間を確保するための仕組みです。単にバージョン番号を振るだけでなく、どのようにリクエストを受け付け、どのロジックを適用するかを制御するアーキテクチャ全体を指します。

SaaSのようなマルチテナント環境では、顧客ごとにAPIの更新速度が異なります。ある顧客は最新機能を即座に利用したい一方で、別の顧客は検証に数ヶ月を要するかもしれません。バージョニングは、この「更新のズレ」を吸収するクッションの役割を果たします。

まとめ

本記事で解説する要点は以下の通りです。

• 破壊的変更の回避: 互換性を維持したままAPIを進化させるための設計思想と、避けるべき変更の具体例。
• バージョニング手法の比較: URIバージョニング、ヘッダーベース、メディアタイプなど、主要なアプローチのメリット・デメリットの比較。
• アダプターパターンの実装: 内部ロジックを共通化しつつ、外部インターフェースのバージョン差異を吸収する実装パターン。
• 運用と廃止計画: APIのライフサイクル管理、Deprecationヘッダーの活用、そして廃止までのプロセス。

破壊的変更と非破壊的変更の境界線

バージョニング戦略を議論する前に、何が「破壊的変更」にあたるのかを明確にする必要があります。一般的に、クライアント側のコード変更を伴わずにアップデートできる場合は「非破壊的」とみなされます。

非破壊的変更の例としては、新しいエンドポイントの追加、既存のレスポンスに新しいオプショナルフィールドを追加する、リクエストパラメータのデフォルト値を変更する（挙動が大きく変わらない場合）などがあります。これらは既存のクライアントにとって「見えない」または「害のない」変更です。

一方で、破壊的変更は既存のクライアントの動作を停止させる可能性があります。具体的には、データ型の変更（例：整数から文字列）、必須フィールドの削除、レスポンス構造の根本的な変更などが挙げられます。これらを行う場合は、必ず新しいバージョンのAPIとして別途公開する必要があります。

主要なバージョニング手法の比較

技術的には、バージョン情報をどこに伝達するかによっていくつかのアプローチがあります。それぞれに一長一短があり、プロダクトの特性に合わせて選択する必要があります。

アプローチ	メリット	デメリット	適したケース
URIパス (/v1/users)	実装が容易、キャッシュサーバーでの扱いが簡単、ブラウザでのテストが容易	URIがリソースそのものではなくバージョンを含んでしまう（純粋なREST原則からは逸脱）	一般的な公開API、B2B SaaS、多くのクライアントが存在する場合
リクエストヘッダー (Accept-Version: v1)	URIをクリーンに保てる、RESTfulな原則に忠実	ブラウザからの直接テストが困難、キャッシュの設定が複雑になる場合がある	プラットフォーム系API、URIの厳格な管理が求められる場合
クエリパラメータ (?version=1)	実装が最も簡単	URIが汚れる、キャッシュキーが膨大になる（バージョンごとにキャッシュが必要）	簡易的なAPI、内部マイクロサービス間通信
コンテンツネゴシエーション (Accept: application/vnd.api.v1+json)	HTTP標準に準拠、柔軟性が高い	クライアント実装のハードルが高い、デバッグが難しい	エンタープライズ向けの厳格なAPI設計

私の経験上、まずは URIパス 方式から始めるのがベストプラクティスです。実装コストが低く、開発者にとって最も直感的だからです。APIが成熟し、数千のエンドポイントを持つようになって初めて、ヘッダーベースへの移行を検討する余地があります。

実装例：バージョニングの適用

ここからは、具体的なコードを見ていきましょう。今回は、URIパス方式とヘッダー方式を組み合わせた、実務レベルの実装をPythonとTypeScriptで紹介します。

実装例1: Python (FastAPI) によるルーティングとミドルウェア

FastAPIを使用して、リクエストヘッダーに基づいて動的にハンドラーを切り替える、あるいは非推奨警告を出す実装例です。

from fastapi import FastAPI, Request, Response, HTTPException, status
from fastapi.responses import JSONResponse
import logging
from typing import Optional, Callable

# ロギングの設定
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

app = FastAPI()

# 非推奨のバージョンを管理するセット
DEPRECATED_VERSIONS = {"2021-01-01"}

# カスタム例外ハンドラー: バージョンがサポート外の場合
class UnsupportedVersionError(Exception):
    def __init__(self, message: str):
        self.message = message

@app.exception_handler(UnsupportedVersionError)
async def unsupported_version_handler(request: Request, exc: UnsupportedVersionError):
    return JSONResponse(
        status_code=status.HTTP_400_BAD_REQUEST,
        content={"detail": exc.message, "supported_versions": ["2024-06-01", "2023-06-01"]},
    )

# ミドルウェア: バージョンヘッダーの検証とログ出力
@app.middleware("http")
async def version_middleware(request: Request, call_next: Callable):
    api_version = request.headers.get("X-API-Version")
    
    # ヘッダーがない場合はデフォルト（最新）を扱う
    if not api_version:
        api_version = "2024-06-01"
        logger.info(f"Default version assigned: {api_version}")
    
    # 状態チェック: 非推奨バージョンの使用
    if api_version in DEPRECATED_VERSIONS:
        logger.warning(f"Deprecated version accessed: {api_version} from {request.client.host}")
        # リクエストは処理するが、レスポンスヘッダーに警告を含める
    
    # 状態チェック: 不明なバージョン
    if api_version not in ["2024-06-01", "2023-06-01"] and api_version not in DEPRECATED_VERSIONS:
        logger.error(f"Unsupported version requested: {api_version}")
        raise UnsupportedVersionError(f"API Version {api_version} is not supported.")

    # 状態オブジェクトにバージョンを保存（ハンドラーで参照可能にする）
    request.state.api_version = api_version

    response = await call_next(request)
    
    # 非推奨バージョンへの警告ヘッダー付与
    if api_version in DEPRECATED_VERSIONS:
        response.headers["X-API-Deprecation"] = "This version is sunset. Please migrate to 2024-06-01."
        response.headers["Link"] = '</docs>; rel="deprecation"'
    
    return response

# エンドポイント実装
@app.get("/users/{user_id}")
async def get_user(user_id: int, request: Request):
    api_version = request.state.api_version
    
    # バージョンによるロジックの分岐
    if api_version == "2024-06-01":
        # 最新版: 詳細なユーザー情報を返す
        return {
            "id": user_id,
            "name": "Taro Yamada",
            "email": "taro@example.com",
            "preferences": {"theme": "dark"} # 新しいフィールド
        }
    elif api_version == "2023-06-01":
        # 旧版: 必須フィールドのみ返す
        return {
            "id": user_id,
            "full_name": "Taro Yamada",
            "contact_email": "taro@example.com"
        }
    elif api_version in DEPRECATED_VERSIONS:
        # 非推奨版: レガシーフォーマット
        return {
            "user_id": user_id,
            "user_name": "Taro Yamada"
        }
    
    raise HTTPException(status_code=500, detail="Internal version mapping error")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

このコードでは、ミドルウェアでバージョンの検証を行い、ハンドラー内で request.state 経由でバージョン情報を取得しています。これにより、ロジックの分岐をコントローラー内に閉じ込めつつ、共通のバリデーションを適用できます。

実装例2: TypeScript (Node.js + Express) によるルーターファクトリパターン

TypeScriptでは、型定義を活用してバージョン間のデータ構造の違いを明確にしながら、ルーターを動的に生成するアプローチが有効です。

import express, { Request, Response, Router } from 'express';

// バージョンごとの型定義
interface UserV1 {
  id: number;
  username: string;
}

interface UserV2 {
  id: string; // UUIDに変更
  name: string;
  email: string;
}

// バージョン管理用の抽象クラス
abstract class ApiVersionHandler {
  abstract getVersion(): string;
  abstract getPath(): string;
  abstract getRouter(): Router;
}

// V1 ハンドラーの実装
class ApiV1Handler extends ApiVersionHandler {
  getVersion(): string { return 'v1'; }
  getPath(): string { return '/v1'; }

  getRouter(): Router {
    const router = express.Router();

    router.get('/users/:id', (req: Request, res: Response) => {
      try {
        const id = parseInt(req.params.id, 10);
        if (isNaN(id)) throw new Error('Invalid ID format');

        // V1 のロジック（DBから取得する想定）
        const user: UserV1 = {
          id: id,
          username: 'legacy_user'
        };
        
        // ログ出力
        console.log(`[V1] Serving user ${id}`);
        
        res.json(user);
      } catch (error) {
        console.error(`[V1] Error: ${error}`);
        res.status(500).json({ error: 'Internal Server Error', version: 'v1' });
      }
    });

    return router;
  }
}

// V2 ハンドラーの実装
class ApiV2Handler extends ApiVersionHandler {
  getVersion(): string { return 'v2'; }
  getPath(): string { return '/v2'; }

  getRouter(): Router {
    const router = express.Router();

    router.get('/users/:id', (req: Request, res: Response) => {
      try {
        const id = req.params.id; // V2はUUID文字列
        
        // V2 のロジック
        const user: UserV2 = {
          id: `uuid-${id}`, // ダミー変換
          name: 'Modern User',
          email: 'user@example.com'
        };

        console.log(`[V2] Serving user ${id}`);
        
        // 非推奨ヘッダー（V1クライアントへの移行促進などで応用可能）
        res.setHeader('X-API-Version', 'v2');
        
        res.json(user);
      } catch (error) {
        console.error(`[V2] Error: ${error}`);
        res.status(500).json({ error: 'Internal Server Error', version: 'v2' });
      }
    });

    return router;
  }
}

// アプリケーションのセットアップ
const app = express();
const handlers: ApiVersionHandler[] = [
  new ApiV1Handler(),
  new ApiV2Handler()
];

// ハンドラーを登録
handlers.forEach(handler => {
  app.use(handler.getPath(), handler.getRouter());
  console.log(`Registered route: ${handler.getPath()} -> ${handler.getVersion()}`);
});

// ヘルスチェック
app.get('/health', (req, res) => {
  res.json({ status: 'ok', versions: handlers.map(h => h.getVersion()) });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

このパターンでは、ApiVersionHandler という基底クラスを定義し、各バージョンのルーターを独立したクラスとして実装しています。これにより、バージョンが増えてもコードの肥大化を防ぎ、各バージョンの責任範囲を明確にできます。

実装例3: アダプターパターンによるデータ変換（TypeScript）

バージョンごとにロジックを完全に分離するとコードが重複します。そこで、内部のビジネスロジックは共通化し、入出力のインターフェースのみを変換する「アダプター」を実装します。

// 共通のビジネスロジック（ドメインモデル）
interface UserDomainModel {
  uuid: string;
  firstName: string;
  lastName: string;
  emailAddress: string;
  isActive: boolean;
}

class UserService {
  // データベースアクセスなどを想定
  async getUserById(uuid: string): Promise<UserDomainModel> {
    return {
      uuid: uuid,
      firstName: 'Hanako',
      lastName: 'Yamada',
      emailAddress: 'hanako@example.com',
      isActive: true
    };
  }
}

// V1用アダプター (Domain -> V1 DTO)
class UserV1Adapter {
  static toDTO(domain: UserDomainModel): any {
    return {
      id: parseInt(domain.uuid.replace(/\D/g, ''), 10) || 0, // UUIDを数値に無理やり変換（レガシー仕様）
      full_name: `${domain.lastName} ${domain.firstName}`, // 名前の順序が逆
      mail: domain.emailAddress // フィールド名が異なる
    };
  }
}

// V2用アダプター (Domain -> V2 DTO)
class UserV2Adapter {
  static toDTO(domain: UserDomainModel): any {
    return {
      id: domain.uuid,
      name: {
        first: domain.firstName,
        last: domain.lastName
      },
      email: domain.emailAddress,
      status: domain.isActive ? 'active' : 'inactive'
    };
  }
}

// コントローラー
async function handleGetUser(req: any, res: any) {
  const userService = new UserService();
  const version = req.headers['Accept-Version'] || 'v1';
  
  try {
    // IDの解決（V1は数値ID、V2はUUIDと想定するが、ここでは簡略化）
    // 実際にはIDマッピングテーブルなどが必要
    const uuid = "12345-e6b7-4"; 
    
    // 共通ロジックの呼び出し
    const userDomain = await userService.getUserById(uuid);

    // バージョンに応じたアダプターの選択
    if (version === 'v2') {
      const dto = UserV2Adapter.toDTO(userDomain);
      return res.json(dto);
    } else {
      // デフォルトはV1
      const dto = UserV1Adapter.toDTO(userDomain);
      return res.json(dto);
    }

  } catch (error) {
    console.error("Service error:", error);
    res.status(500).json({ message: "Internal Error" });
  }
}

// Expressアプリへの登録例
// app.get('/users/:id', handleGetUser);

export { handleGetUser, UserService, UserV1Adapter, UserV2Adapter };

このアプローチの利点は、ビジネスロジック（UserService）にバージョン依存のロジックが入り込まない点です。ドメインモデルは純粋に保たれ、変換ロジックだけが各バージョンの仕様に追従します。

アーキテクチャ図：リクエストの流れ

バージョニング導入時のリクエストフローをシーケンス図で表現します。クライアントからのリクエストが、どのようにルーティングされ、適切なアダプターを経由してレスポンスが返されるかを可視化しています。

sequenceDiagram
    participant Client
    participant API Gateway
    participant Router
    participant V1 Handler
    participant V2 Handler
    participant Core Service

    Client->>API Gateway: GET /users/123 (Header: X-Version=v1)
    
    alt Version Check
        API Gateway->>API Gateway: Validate Version Header
        API Gateway-->>Client: 400 Bad Request (Invalid Version)
    else Valid Version
        API Gateway->>Router: Route to /v1/users
        Router->>V1 Handler: Request
        
        Note over V1 Handler: Check Cache / Auth
        
        V1 Handler->>Core Service: getUserData(123)
        Core Service-->>V1 Handler: DomainModel
        
        Note over V1 Handler: Apply V1 Adapter<br/>(Transform Data)
        
        V1 Handler-->>Client: 200 OK (V1 JSON Format)
    end
    
    Client->>API Gateway: GET /users/123 (Header: X-Version=v2)
    API Gateway->>Router: Route to /v2/users
    Router->>V2 Handler: Request
    V2 Handler->>Core Service: getUserData(123)
    Core Service-->>V2 Handler: DomainModel
    Note over V2 Handler: Apply V2 Adapter
    V2 Handler-->>Client: 200 OK (V2 JSON Format)

ビジネスユースケース：決済システムのアップグレード

具体的なビジネスシナリオとして、決済処理APIのアップグレードを考えます。あるSaaS企業が、決済プロバイダーをA社からB社へ変更することになったとします。これはAPI仕様において極めて大きな破壊的変更を伴います。

• 旧API (v1): クレジットカード番号を直接受け取り、A社のSDKで処理。
• 新API (v2): トークン化された決済IDのみを受け取り、B社のAPIを叩く。

ここで、一斉にv1を停止させると、決済処理を組み込んでいる顧客の売上が即座に止まるリスクがあります。そこで、以下のような移行計画を立てます。

1. 並行運用期間: v1とv2を両方稼働させる。v1へのリクエストは裏でB社のAPI（または互換レイヤー）に変換して処理するか、一時的にA社を維持する。
2. アナウンス: 「v1は2026年12月で廃止します」と、APIレスポンスヘッダーやメールで顧客に周知する。
3. 移行支援: v2のドキュメント提供と、移行用のスクリプト提供を行う。
4. モニタリング: v1のトラフィックが減少していることを確認しつつ、最終的にv1を遮断する。

このように、バージョニング戦略は技術的な問題解決だけでなく、ビジネス的なリスクヘッジとして機能します。

よくある質問

旧バージョンのAPIを永久にサポートし続ける必要はありますか？

基本的には不要です。無限にバージョンをサポートし続けると、コードベースが複雑化し、保守コストが膨らむからです。一般的には、非推奨（Deprecate）のアナウンスから6ヶ月〜1年程度の移行期間を設け、その後廃止（Sunset）するのがスタンダードです。ただし、エンタープライズ向けの契約などでSLA（サービス品質保証）に含まれている場合は、契約期間に応じてサポート期間を延長する柔軟な対応が必要です。

データベースのスキーマ変更が伴う場合、どう実装すべきですか？

データベースの変更はAPIのバージョニング以上に複雑です。「Expand and Contract」パターン（拡張と縮小）が推奨されます。まず、新旧どちらのAPIでも扱える新しいカラムを追加します（Phase 1: Expand）。次に、アプリケーションコードを徐々に新しいカラムを使うように書き換え、デプロイします（Phase 2: Migrate）。最後に、古いカラムが参照されなくなったタイミングで、古いカラムを削除します（Phase 3: Contract）。このプロセスを踏むことで、データベースの変更によるダウンタイムを防げます。

URIバージョニングとヘッダーバージョニング、どちらを選ぶべきでしょうか？

迷ったらURIバージョニング（例: /api/v1/resource）をお勧めします。理由は、デバッグが容易であること（ブラウザでURLを叩くだけで確認できる）、CDNやプロキシサーバーでの設定が直感的であること、そして開発者がバージョンの違いを視覚的に認識しやすいからです。ヘッダーバージョニングはURIの純粋性を保てますが、開発体験の面では少しハードルが上がります。大規模なプラットフォームでなければ、URI方式で十分に運用可能です。

マイクロサービス間の通信でもバージョニングは必要ですか？

はい、必要です。ただし、外部向けのAPIほど厳密である必要はありません。マイクロサービス間は同じチームが管理することが多く、全サービスを同時にデプロイする権限を持っている場合が多いためです。しかし、大規模な組織や複数のチームが関わる場合、あるいはCanary Release（カナリアリリース）を行う場合は、サービス間でもバージョン管理を行い、トラフィックを徐々に新しいバージョンに流す制御が重要になります。

GraphQL APIの場合のバージョニングはどうなりますか？

GraphQLでは、フィールドの追加は非破壊的変更ですが、フィールドの削除や型変更は破壊的変更となります。GraphQLのコミュニティでは、「URLバージョニングよりもスキーマの進化（Schema Evolution）で対応すべき」という考え方が主流です。具体的には、フィールドを削除する代わりに @deprecated ディレクティブを付与して非推奨とし、クライアントの移行を待ちます。どうしても破壊的変更が必要な場合は、URL自体を /v2/graphql とするなどのバージョニングを行います。

おわりに

SaaS APIのバージョニングは、単なる技術的なタスクではなく、製品の信頼性と進化速度のバランスを取るための重要な戦略です。破壊的変更を恐れて革新を止めるのではなく、適切なバージョニング戦略と実装パターンを武器に、顧客に安心を提供しながら製品を前に進めましょう。

私たちが提供するSaaSソリューションでは、このような堅牢なAPI設計を基盤としたアーキテクチャ支援を行っています。API設計における課題や、より具体的な導入支援についてご興味が