こんにちは！ネットワークの裏側や、データが世界中を駆け巡る仕組みを愛してやまないインフラエンジニアの私です。
Webアプリケーションを作ったり、スマホアプリとデータをやり取りしたりするときに欠かせないのが「Web API」ですよね。皆さんも一度は使ったことがあるのではないでしょうか？
さて、このAPI、最初は順調に動いていたのに、サービスが成長するにつれて「あそこのデータを別の形式に変えたい！」「新しい機能を追加したい！」というタイミングが必ずやってきます。しかし、ここで怖いのが「今まで使ってくれていたユーザーのアプリが、アップデートした途端に動かなくなっちゃった…！」という事態です。いわゆる「破壊的変更（Breaking Changes）」と呼ばれるものですね。
こうした悲劇を防ぎ、古いアプリも新しいアプリも仲良く動かすために使われるのが「APIのバージョン管理戦略」です。
今回は、このバージョン管理の代表的な3つの方法（URLパス、クエリパラメータ、ヘッダー）について、身近な「郵便配達」の仕組みに例えながら、インフラやキャッシュへの影響も含めて一歩ずつ優しく紐解いていきましょう！
—
1. なぜAPIのバージョン管理が必要なの？（現実世界に例えてみよう）
いきなり難しい技術の話をする前に、身の回りの「手紙や荷物のやり取り」を想像してみてください。
例えば、あなたが友人に荷物を送るとします。
最初は「宛先と名前」だけで荷物が届いていたとしましょう。しかし、ある日あなたが「これからは『郵便番号・住所・氏名・電話番号』の4つが揃っていないと配達を受け付けません！」というルールに変えたとします。
もし、この変更を事前に知らせず、昔のルール（宛先と名前だけ）で荷物を送ってきた友人がいたらどうなるでしょうか？ 配達員さんは「住所がないからどこに届けていいかわからない！」と困ってしまい、荷物は迷子になってしまいますよね。
APIの世界もこれと全く同じです。
サーバー側（郵便局や配達員）がルールを勝手にガラッと変えてしまうと、クライアント側（荷物を送る側）のアプリがパニックを起こしてしまいます。だからこそ、「私は今まで通りの『バージョン1』のルールで受け取りますよ」「新しくできた『バージョン2』のルールでお願いします」と、宛先を明確に区別してあげる必要があるのです。
それでは、このバージョンを区別するための3つのアプローチを、インフラエンジニアの視点も交えながら見ていきましょう！
—
2. 代表的な3つのバージョン管理戦略
APIのバージョンを切り替える方法は、主に以下の3つに分かれます。
1. URLパス方式 （一番人気で直感的）
2. クエリパラメータ方式 （おまけ情報として添える）
3. カスタムヘッダー方式 （封筒の裏側にこっそり書く）
それぞれの特徴を、メリット・デメリットと共により詳しく見ていきましょう。
—
① URLパス方式（URLの中にバージョンを含める）
最も一般的で、世界中の多くのWebサービス（StripeやGitHubなど）で採用されている王道スタイルです。
- URLの例:
https://api.example.com/v1/usersとhttps://api.example.com/v2/users
メリットとインフラ的な挙動
何と言っても「人間にとって圧倒的に分かりやすい」のが最大のメリットです。ブラウザの履歴やログを見ただけで、「あ、これは古いバージョンの通信だな」が一目でわかります。
また、ネットワークやインフラの視点（ルーターやロードバランサー、APIゲートウェイなど）からも非常に扱いやすいという特徴があります。例えば、v1宛ての通信は古いサーバー群へ、v2宛ての通信は最新のサーバー群へと、URLの文字（パス）を見るだけで簡単に交通整理（ルーティング）ができるのです。
デモコード（Python / FastAPIの例）
実際にコードを書くときは、次のようにパスの中にバージョンを組み込みます。
from fastapi import FastAPI
app = FastAPI()
# バージョン1用のエンドポイント
@app.get("/v1/users")
def get_users_v1():
# 古い形式のデータを返す（例：名前と年齢のみ）
return [{"name": "山田太郎", "age": 28}]
# バージョン2用のエンドポイント（新しい形式）
@app.get("/v2/users")
def get_users_v2():
# 新しい形式のデータを返す（IDやメールアドレスを追加）
return [{"id": 101, "full_name": "山田 太郎", "email": "yamada@example.com"}]—
② クエリパラメータ方式（URLの後ろに ?version=1 のようにつける）
URLの末尾に、おまけのパラメータとしてバージョンを指定する方法です。
- URLの例:
https://api.example.com/users?version=1とhttps://api.example.com/users?version=2
メリットとインフラ的な挙動
同じベースのURL（https://api.example.com/users）を使い回せるため、パッと見のURLをシンプルに保ちたい場合に選ばれることがあります。
しかし、インフラやキャッシュの世界では少し厄介者になることがあります。
Webの世界には、同じリクエストが来たらサーバーまで行かずに途中でおいしいデータを返す「CDN（コンテンツ配信ネットワーク）」や「リバースプロキシ」というキャッシュの仕組みがあります。
URLパス方式であれば /v1/users と /v2/users は完全に別のURLとしてキャッシュされますが、クエリパラメータ方式の場合、プロキシの設定によっては ?version=1 と ?version=2 を同じURL（https://api.example.com/users）とみなしてしまい、「本当はバージョン2が欲しいのに、キャッシュに残っていたバージョン1の古いデータが返されてしまった！」というトラブル（キャッシュ汚染）が起きやすくなります。そのため、設計する際は注意が必要です。
—
③ カスタムヘッダー方式（HTTPヘッダーにこっそり指定する）
URLを汚さず、通信の「裏側（HTTPヘッダー）」にバージョン情報を潜ませるスタイルフリークな方法です。
- リクエストのイメージ:
- URL:
https://api.example.com/users - ヘッダー:
X-API-Version: 2（またはAccept: application/vnd.example.v2+jsonなど）
メリットとインフラ的な挙動
URLが常に美しく汚れないため、「REST APIの原則（リソースの識別はURIで行うべき）」という厳格な美学を好むアーキテクトに支持されます。
一方で、ブラウザのURLバーに直接打ち込んで動作確認がしづらかったり、APIクライアントツール（PostmanやcURLなど）できちんとヘッダーを設定してあげないと意図したバージョンが返ってこなかったりと、初学者やクライアント側の開発者にとっては少しハードルが高くなるデメリットがあります。
また、先ほどのキャッシュの話と同様に、URLだけでキャッシュの切り分けができないため、CDN側のキャッシュ設定（「このヘッダーの値が変わったら別のキャッシュとして扱う」という設定）を細かくチューニングする必要があり、インフラ側の運用コストが少し上がります。
—
3. 結局、どれを選ぶべき？（実務で迷ったら）
「結局、私たちはどれを使えばいいの？」という疑問が湧いてきますよね。
結論からお伝えすると、特段のこだわりや複雑な要件がない限り、①の「URLパス方式」を選ぶのが最も無難で、トラブルが少ないベストプラクティスです。
理由は以下の通りです。
- ブラウザやログ、ネットワーク機器（ロードバランサー等）から見て「何をしているのか」が一番わかりやすい。
- キャッシュの制御が直感的で、古いバージョンと新しいバージョンが意図せず混ざる事故を防ぎやすい。
- クライアント（アプリやフロントエンドのエンジニア）の実装ミスが起きにくい。
技術の世界では「シンプルで誰もが迷わない仕組み」が最強の武器になります。まずはURLパス方式から設計を始めてみるのが、現場でも一番おすすめですよ。
—
4. まとめ
今回は、APIのバージョン管理戦略について、現実世界の郵便配達やインフラのキャッシュ、ルーティングの視点を交えながら解説しました。
- URLパス方式 (
/v1/...): 人間にもインフラにも優しく、キャッシュも安全。迷ったらこれ！ - クエリパラメータ方式 (
?version=1): URLの見た目はスッキリするが、キャッシュの扱いに注意が必要。 - カスタムヘッダー方式 (
X-API-Version): URLは美しいが、デバッグやインフラのキャッシュ設定の難易度が少し上がる。
APIのバージョン管理は、単なるプログラミングのテクニックではなく、「クライアント（利用者）とサーバー（提供者）の信頼関係を長く続けるためのインフラ設計」そのものです。
「一歩ずつ理解していきましょう！」の精神で、ご自身のプロジェクトに一番フィットするスマートな設計を見つけてみてくださいね。それでは、また次回の技術解説でお会いしましょう！
コメント