【実務・中級編】 APIのバージョン管理戦略：URLパス、クエリパラメータ、ヘッダーによる切り替え – Web APIアーキテクチャ・データ連携実践ガイド

APIのバージョン管理、その「終わらない戦い」に終止符を打つ設計戦略

ネットワークエンジニアとして数々のAPIゲートウェイのログを追ってきた経験から言わせてもらえば、APIのバージョン管理は「技術的な選択」である以上に、「運用コストと将来の負債とのバーター取引」です。

Web APIの設計において、後方互換性をどう担保するか。これはRESTの原則をどう解釈するかという哲学的な問いでもありますが、同時に深夜のオンコールを減らすための泥臭い防衛策でもあります。今回は、実務でよく遭遇する3つのバージョン管理手法を、インフラエンジニアの視点で解剖していきます。

—

1. URLパスによる管理（URI Versioning）

最も一般的で、視認性が高い手法です。https://api.example.com/v1/users のように、パスの先頭にバージョンを刻み込みます。

メリットと現場のリアル

メリット: キャッシュ制御が容易です。プロキシやCDN、APIゲートウェイレベルで /v1/ と /v2/ を別のバックエンドにルーティングするのが極めてシンプル。
現場の教訓: ログ解析が楽です。どのバージョンでエラーが多発しているかがURLを見ただけで一目瞭然です。

実装例（Nginxによるルーティング）

# APIゲートウェイでの振り分け設定
location /v1/ {
    proxy_pass http://v1_backend_cluster; # v1用のクラスタへ転送
}
location /v2/ {
    proxy_pass http://v2_backend_cluster; # v2用のクラスタへ転送
}

—

2. クエリパラメータによる管理（Query Parameter Versioning）

https://api.example.com/users?version=2 のように、クエリ文字列で指定します。

メリットと現場のリアル

メリット: 実装が安直です。コード側で if request.args.get('version') == '2' と書くだけで済むため、小規模なAPIでは重宝されます。
現場の教訓: 実はこれ、インフラ屋泣かせです。CDNのキャッシュキー設定が複雑になりがちで、パラメータの順序や有無でキャッシュミスが多発します。「なぜか新バージョンが反映されない」という問い合わせの8割は、ここがキャッシュキーに含まれていないことが原因です。

—

3. ヘッダーによる管理（Custom Header / Content Negotiation）

HTTPヘッダーに Accept: application/vnd.myapi.v2+json のような独自メディアタイプを指定する方法です。

メリットと現場のリアル

メリット: URLをリソースの識別子として純粋に保てます。「RESTの原則（リソースはURIで一意に特定されるべき）」に最も忠実なのはこの方法です。
現場の教訓: 開発者体験（DX）が最悪になりがちです。ブラウザから直接叩く場合や、curlでテストする際に毎回ヘッダーを付与する必要があり、初心者が「APIが動かない！」と詰まる原因の筆頭です。

curlによるリクエスト例

# ヘッダーによるバージョン指定の典型例
curl -H "Accept: application/vnd.myapi.v2+json" \
     -H "Authorization: Bearer <TOKEN>" \
     https://api.example.com/users/123

—

運用負荷の比較：どれを選ぶべきか？

| 手法 | 可読性 | キャッシュ制御 | 開発の容易さ | 推奨シーン |
| :— | :— | :— | :— | :— |
| URLパス | 最高 | 容易 | 容易 | 大規模公開API、CDN活用時 |
| クエリ | 普通 | 難しい | 最高 | 社内向け、小規模API |
| ヘッダー | 低い | 非常に困難 | 低い | 厳密なREST設計を好む環境 |

結論から言えば、迷ったら「URLパス」を選んでください。
インフラ運用において、ルーターやロードバランサー、CDNの設定変更が容易であることは正義です。複雑なヘッダー解析をアプリケーション層で行うよりも、ネットワーク境界でトラフィックを制御できるアーキテクチャの方が、トラブル時の切り分けが圧倒的に早いです。

—

デバッグのためのTips：Pythonでの切り替え実装（サンプル）

最後に、Python（FastAPIを想定）でのシンプルかつ堅牢な実装イメージを載せておきます。

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

# ヘッダーベースで処理を分岐させる例
@app.get("/users")
async def get_users(x_api_version: str = Header("1")):
    if x_api_version == "1":
        return {"data": "v1のレガシーなデータ構造"}
    elif x_api_version == "2":
        return {"data": "v2の洗練されたデータ構造"}
    else:
        raise HTTPException(status_code=400, detail="Unsupported Version")

# 実際の現場では、これらを別々のモジュールに切り出し、
# 依存関係を分離しておくのが「死なない」設計の秘訣です。

最後に

APIのバージョン管理は、APIが「生き物」であることの証です。完璧な設計を目指して思考停止するよりも、「今の運用チームが深夜に障害対応で泣かない構成」を優先してください。パスによる分離は、そのための最も強力な武器になります。

さあ、次はどのプロトコルの深淵を覗きましょうか。質問があればいつでもどうぞ。