APIバージョニング

📖 もうちょい詳しく

何が新しいの？

APIは、外部のアプリやサービスにデータをやりとりさせる「窓口」です。ところが一度公開すると、たくさんの利用者がその仕様をあてにして作り込みます。そこで仕様を変えるときに、古い利用者を壊さずに新しい形も出すための工夫が「APIバージョニング」です。

どうやって動いてるの？

やり方の中心は、APIに版番号（v1・v2など）を持たせて、古い版と新しい版を同時に動かしておくことです。番号の置き場所はいくつかあって、住所にあたるURLに入れる（例：/v1/users）、リクエストの付箋にあたるヘッダーで指定する、といった方法がよく使われます。利用者は自分が対応した版を選んで呼びにいきます。

何ができるの？

新しい機能を追加したり項目名を変えたりしても、古い版をしばらく残せます。だから利用者は、自分の都合のよいタイミングで新しい版に乗り換えられます。提供する側も「古い版はいつ止めます」と予告しながら、混乱を抑えて仕様を進化させられます。

🌱 身近なたとえ

電車の時刻表で例えると分かりやすいです。ダイヤを変えるとき、いきなり新ダイヤだけにすると、古い時刻表を見ている人が乗り遅れます。そこで「○月○日から新ダイヤ」と告知して、しばらくは旧ダイヤの案内も残しておきます。APIの版番号も、この「新旧をしばらく併走させて、案内つきで切り替える」ための仕組みです。

✅ まず覚えるポイント

• バージョニングは、APIの仕様を変えても古い利用者を壊さないための工夫です。
• v1・v2のような版番号で、古い形と新しい形を見分けます。
• 版番号は、URLに入れる方法とヘッダーで指定する方法がよく使われます。
• 古い版と新しい版を、しばらく同時に動かしておけます。
• 互換性を壊す変更（項目の削除や型の変更など）をするときに必要になります。
• 古い版を止めるときは、事前の予告（廃止のアナウンス）が大切です。

🧭 よくある勘違い

番号を上げれば毎回バージョンを増やすの？

いいえ、上げるのは「互換性を壊す変更」をするときが中心です。項目を新しく足すだけ、といった古い利用者に影響しない変更なら、同じ版のまま進められることが多いです。番号を増やすほど両方の面倒を見る手間が増えるので、必要なときに絞るのがふつうです。

バージョニングをすれば永遠に古い版を残せるの？

残し続けるほど、保守する範囲が広がって負担になります。多くの現場では「古い版はいつまでサポートします」と期限を決めて、利用者に乗り換えを促します。やさしく見える仕組みですが、いつかは整理する前提で運用される場合が多いです。

🧩 関連して覚えると楽な言葉

• API: アプリ同士がデータをやりとりする窓口。バージョニングはこの窓口の仕様を管理する話です。
• REST: URLとHTTPで作るAPIの代表的な作法。版番号をURLに入れる方法と相性がよいです。
• エンドポイント: APIの呼び出し先となる具体的な住所。/v1/usersのように版番号が入ることがあります。
• バージョン管理: ソースコードの変更履歴を残す仕組み。「版を分けて管理する」考え方が共通しています。

🏁 ひとことでまとめ

APIに版番号をつけ、新旧をしばらく並べて動かすことで、仕様を進化させても利用者を急に困らせない――それがAPIバージョニングです。