APIバージョニング とは？

APIを公開したあとに「このフィールドをなくしたい」「レスポンスの形を変えたい」と思っても、すでに使っているクライアントが壊れてしまうんだ。バージョニングをしておけば古いクライアントはv1を使い続けて、新しい機能はv2に移行する、という対応ができるよ。

`/api/v1/users` と `/api/v2/users` みたいにパスにバージョン番号を入れるのが一番分かりやすくて多くのAPIで使われているよ。他にも `?version=2` のクエリパラメータや、`Accept: application/vnd.api+json;version=2` というHTTPヘッダーで指定する方式もあるんだ。

URLパス方式が最も分かりやすくてキャッシュもしやすい。ヘッダー方式はURLが汚れないけどブラウザで直接試しにくい。それぞれトレードオフがあるから、チームの用途に合わせて選ぶんだよ。

ここが実際の運用で一番難しいんだよ。「v1は〇月〇日で廃止します」と告知しても、使い続けるクライアントがいることが多くて、廃止しきれないことがある。一般的には非推奨（deprecated）の期間を設けて、移行ガイドを作り、APIのレスポンスに「この版は廃止予定です」というヘッダーを付ける。社内APIでも外部APIでも「古いバージョンがいつまでも残る」問題は世界中で起きていて、セマンティックバージョニングの思想と組み合わせてライフサイクルを明文化することが大切だよ。