API・メッセージング

APIバージョニングえーぴーあいばーじょにんぐ

APIバージョン管理後方互換性RESTful APIエンドポイント破壊的変更

APIバージョニングについて教えて

簡単に言うとこんな感じ！

APIに「v1」「v2」って番号をつけて、古いバージョンも新しいバージョンも同時に動かせるようにする仕組みだよ！スマホアプリをすぐ更新しないユーザーでも、壊れずに使い続けられるように守ってあげる仕掛けってこと！

APIバージョニングとは

APIバージョニングとは、API（アプリケーション同士をつなぐ窓口）に対して変更を加えるとき、既存の利用者を壊さないように「バージョン番号」で新旧を区別して管理する手法です。たとえば https://api.example.com/v1/users と https://api.example.com/v2/users のように、URLにバージョンを含めることで、古いシステムはv1を、新しいシステムはv2を使い続けられます。

APIを提供する側が仕様を変えたいとき、いきなり変更してしまうと、そのAPIを使っているアプリやシステムが突然動かなくなってしまいます（これを破壊的変更と呼びます）。バージョニングはその事故を防ぐための「猶予期間付きの移行ルール」です。スマホアプリを例にとれば、ユーザーが古いアプリを使っていても、v1 APIが生きている間はちゃんと動く——という状態を作り出せます。

ビジネスの観点では、APIの安定性はサービスの信頼性に直結します。「APIが突然壊れた」という事態はパートナー企業や開発会社との信頼を損ねるため、計画的なバージョニング戦略はシステム発注・選定の際に確認すべき重要な品質指標のひとつです。

バージョニングの主な方式

APIにバージョンを伝える方法は複数あります。それぞれ一長一短があり、プロジェクトの性質や利用者の種類によって使い分けます。

方式	例	メリット	デメリット
URLパス方式	`/v1/users`	わかりやすい・ブラウザで確認しやすい	URLが増える・RESTの純粋性が下がる
クエリパラメータ方式	`/users?version=1`	URLの構造を変えずに済む	キャッシュされにくい場合がある
HTTPヘッダー方式	`Accept: application/vnd.myapi.v1+json`	URLがシンプル・RESTに忠実	見えにくい・テストしにくい
ホスト名方式	`v1.api.example.com`	環境ごとに完全分離できる	DNS管理が複雑になる

覚え方：「URLが一番わかりやすい」

実務で最も広く使われているのはURLパス方式（/v1/）です。エンジニアでなくてもURLを見ればバージョンがわかるため、ベンダーとの仕様確認や契約書への記載もしやすいのが特徴です。「迷ったらURLにv番号」と覚えておけばOKです。

バージョン番号の種類

表記	意味	例
メジャーバージョン	破壊的変更あり	v1 → v2
マイナーバージョン	後方互換の機能追加	v1.1 → v1.2
パッチバージョン	バグ修正のみ	v1.1.0 → v1.1.1

セマンティックバージョニング（SemVer）と呼ばれる MAJOR.MINOR.PATCH 形式が広く使われており、APIの変更がどの程度の影響を及ぼすかを数字で表現します。

歴史と背景

2000年代前半：Webサービスが普及し始め、外部公開APIが登場。当初はバージョン管理の概念が薄く、変更のたびに利用者が壊れる問題が頻発した
2004年頃：Amazon Web Services（AWS）がAPIを外部公開。変更管理の重要性が業界で認識され始める
2000年代後半：Twitter・Facebook・Google Maps などが公開APIを提供し、バージョン管理のベストプラクティスが議論されるようになる
2010年：Roy FieldingのREST原則に基づくAPIが主流になり、URLパス方式のバージョニングが広まる
2013年頃：セマンティックバージョニング（SemVer 2.0.0） が Tom Preston-Werner によって策定・公開され、バージョン番号の意味を明確化する共通言語が生まれる
2015年以降：マイクロサービスアーキテクチャの普及により、サービス間のAPI互換性管理がより重要な課題となり、バージョニング戦略が設計の必須要素に

破壊的変更と後方互換性

バージョニングを理解するうえで最も重要な概念が「破壊的変更（Breaking Change）」と「後方互換性（Backward Compatibility）」です。

破壊的変更の例：

レスポンスのフィールド名を変える（user_name → username）
必須パラメータを追加する
エンドポイントのURLを変える
認証方式を変える

後方互換の変更の例：

新しいフィールドをレスポンスに追加する（既存フィールドはそのまま）
新しいエンドポイントを追加する
任意パラメータを追加する

以下の図は、バージョン移行のフローと利用者への影響を示しています。

廃止（Deprecation）ポリシーも重要です。バージョンを廃止する際は、一定の猶予期間（通常6か月〜1年）を設けて利用者に移行を促すのが業界標準です。発注側は「古いバージョンのサポート期限はいつまでか」をベンダーに必ず確認しましょう。

規格・RFC番号	内容
RFC 9110	HTTP Semantics（APIの土台となるHTTPの意味論的定義）
RFC 7231	HTTP/1.1のメソッド・ステータスコード・コンテントネゴシエーション（ヘッダー方式バージョニングの基礎）
RFC 6906	The ‘profile’ Link Relation Type（APIプロファイルによるバージョン表現の参考規格）