API versioning とは？インターフェースを壊さずに進化させる

API versioning は、クライアントが移行するまで、新しいバージョンのインターフェースを古いものと並行して動かすことで breaking change を導入できます。

breaking change が避けられないこともあります。API versioning は、すべてのクライアントに一斉更新を強制せずにそれを出荷する方法です。新しいバージョンを公開し、古いものを稼働させたまま、consumer が自分のスケジュールで移行できるようにします。その代償は、古いものを引退させられるまで複数バージョンを保守しテストすることです。

そもそもなぜバージョン管理するのか

バージョン管理された API は、breaking change を伴っても、すべてのクライアントを協調させずに進化できます。古いクライアントは古いバージョンにとどまり、新しいクライアントは新しいものを採用します。この分離は、公開 API や大規模なマイクロサービス群にとって不可欠です。

一般的な戦略

URL path のバージョン管理 (/v1/, /v2/) - 明示的でルーティングが容易。
header または media-type によるバージョン管理 - URL を安定に保つ。
query-parameter によるバージョン管理 - 単純だが見落としやすい。
バージョン管理なし、追加的な変更のみ - 決して壊さないなら成り立つ。

複数バージョンのコスト

稼働中の各バージョンは、保守・テスト・保護しなければならないコードです。バージョンは積み重なるため、告知・sunset・削除という deprecation ポリシーが、対象範囲が際限なく増えるのを防ぎます。

サポート対象の各バージョンをテストする

CI は稼働中の各バージョンを、しばしば matrix としてテストし、新しいものが進化する間にどれも退行しないようにする必要があります。パイプラインはサポートするバージョン数とともに大きくなり、それ自体が古いものを速やかに引退させる論拠になります。

新しいバージョンをデプロイする

新しいバージョンは通常、追加的に出荷され、古いものは提供を続けるため、デプロイ自体は非 breaking です。breaking change は新しいバージョンの内側に封じ込められるため、ロールアウトは安全で rollback は単純になります。

高速な runner でのバージョン matrix

複数の API バージョンを並行してテストするのは自然な matrix build です。スケールアウトするマネージド runner（Latchkey など）は、それらのバージョンジョブを並行実行するため、追加のカバレッジがあってもスイートが素早く終わります。

重要なポイント

API versioning は、新旧のインターフェースバージョンを並行して動かす。
同期的なクライアント更新を強制せずに breaking change を出荷できる。
稼働中の各バージョンは保守とテストのコストなので、古いものは意図的に deprecate する。