Google における API のバージョニング

API のバージョニングは簡単ではありません。いろいろな方法があり、API の世界の人なら誰でも持論をお持ちでしょう。バージョニングを避けることもほとんど不可能です。開発チームが仕事を進めると、機能を廃止（または、その機能を別の形で提供）する必要が生じることがあります。バージョニングを導入すれば、API のユーザーは API のセマンティクスの変化を確実に把握できるようになります。

複数のバージョンを設けないようにする会社もありますが、Google にはそのような余裕はありません。Google の API の数、API を開発しているチームの数、API を使っている開発者の数があまりにも多いので、どのような機能が API に期待されているのか、それを知るための手段として私たちは API をバージョニングしています。

API のバージョニングには一貫性のある包括的なポリシーが必要です。Google ではセマンティック バージョニングの一般原則に従って API にバージョンを付けています。この原則は単純で、各リリースにはメジャー バージョンの X とマイナー バージョンの Y という 2 つの数字を与えます。マイナー バージョンが変わっても下位互換性は失われませんが、メジャー バージョンが変わると下位互換性が失われます。

Google のメジャー バージョンは API のパスに反映され、ドメインのすぐ後ろに組み込まれます。こうすれば、同じ API URL を呼び出す限り、返されるフィールドが消えたり名前が変わったりしないことが保証されます。たとえば、coolcloudapi.googleapis.com/v1/coolthings/12301221312132 に対して GET 命令を送ったとき、返される JSON のフィールドは消えたり名前が変わったりしません。

もちろん、この方法には長所と短所があります。現在も、多くの優秀な人々が「正しい」バージョニングに関して議論を戦わせています。バージョンの指定にはヘッダを使うべきだという人もいれば、API コンシューマーが使い慣れたバージョンを堅持すべきだという人もいます。

こうした意見を私たちはすべて検討し、バージョニングの広範な目的に照らし合わせたうえで、URL にメジャー バージョンを組み込むことがほとんどのケースで最も効果的だという結論に達しました。

URL にマイナー バージョンが含まれていないことに注意してください。そのため、私たちが Cool Cloud API に新フィールドを追加しても URL は変わらず、coolcloudapi.googleapis.com/v1/coolthings/12301221312132 を呼び出すとある日突然新しいデータが返されるようになり、ユーザーに驚かれることがあります。しかし私たちは、アプリケーションを「壊す」ようなフィールドの削除は決して行いません。

私たちが新しいメジャー バージョンをリリースするときは、通常は両方のバージョンを処理できる単一のバックエンドを作ります。バージョンの違いにかかわらず、すべての要求はこのバックエンドに送られます。バックエンドは、パス内のバージョンを使ってどちらを返すかを判断します。

私たちは、Google の API ゲートウェイである Cloud Endpoints のお客様を対象に、上記と同じバージョニングの方法を使用できるようにしました。

まず第 1 に、私たちのプロキシは、お客様の API の複数のバージョンに対応し、API バージョンを返すようになります。これを使えば、API のどのバージョンにどれだけのトラフィックが集まるかがわかります。新バージョンに移行した API へのトラフィックがどれだけあるかが把握できるわけです。

第 2 に、これを利用すれば、古いバージョンを使っているユーザーを特定し、それを基に API を非推奨や廃止に導くことができます。このテーマについては後日改めてブログで取り上げるつもりです。

バージョニングは、より良い API を作るという薔薇のとげのようなものです。私たちは社内で採用したアプローチに自信を持っており、コミュニティとともに作り上げたベスト プラクティスをシェアしたいと思っています。

Cloud Endpoints をぜひ使ってみてください。詳細は、10-minute-quickstart もしくは in-depth tutorials をご覧いただくか、私たちの Google グループ google-cloud-endpoints@googlegroups.com にご連絡ください。

* この投稿は米国時間 6 月 26 日、Product Manager である Dan Ciruli によって投稿されたもの（投稿はこちら）の抄訳です。

- By Dan Ciruli, Product Manager