バージョニング

このトピックでは、Google API で使用されるバージョニング戦略について説明します。通常、これらの戦略はすべての Google マネージド サービスに適用されます。

下位互換性のない(互換性を損なう)変更を API に加える必要がある場合もあります。このような変更は、元の機能に依存するコードの問題や破損を引き起こす可能性があります。

Google API はバージョニング スキームを使用して、互換性を破る変更を防止します。さらに、Google API は、アルファ コンポーネントやベータ コンポーネントなど、特定の安定性レベルでのみ利用可能な一部の機能を提供します。

ガイダンス

すべての Google API インターフェースは、メジャー バージョン番号(protobuf パッケージの最後にエンコードされ、REST API の URI パスの最初の部分として含まれます)を提供する必要があります。API でフィールドの削除や名前変更など、互換性のない変更が行われた場合は、既存のユーザーコードが突然破損しないように、API のバージョン番号を増やす必要があります。

API の新しいメジャー バージョンは、同じ API の以前のメジャー バージョンに依存してはいけません。呼び出し元は、その API に関連する依存関係と安定性のリスクを理解していることを期待して、API は他の API に依存する場合があります。このシナリオでは、安定した API バージョンは他の API の安定したバージョンにのみ依存する必要があります。

同じ API の異なるバージョンは、適切な移行期間にわたって、単一のクライアント アプリケーション内で同時に動作できる必要があります。この期間により、クライアントは新しいバージョンにスムーズに移行できます。古いバージョンは、シャットダウンされる前に、十分に伝達された適切な非推奨期間を経過する必要があります。

アルファ版またはベータ版の安定性のリリースを行う場合、API では、protobuf パッケージと URI パスのメジャー バージョン番号の後に、安定性レベルを次のいずれかの方法で追加する必要があります。

  • チャンネル ベースのバージョニング(推奨)
  • リリース ベースのバージョニング

チャンネル ベースのバージョニング

安定性チャンネルとは、インプレース更新を受け取る、指定された安定性レベルの長期リリースです。メジャー バージョンには、安定性レベルごとに複数のチャンネルはありません。この方法では、アルファ、ベータ、ステーブル の 3 つのチャンネルを使用できます。

アルファとベータのチャンネルは、安定性レベルをバージョンに追加しなければなりませんが、ステーブル チャンネルは安定性レベルを追加してはいけません。たとえば、ステーブル チャンネルでは、v1 は使用できるバージョンですが、v1betav1alpha は使用できません。同様に、v1betav1alpha は、アルファ チャンネルやベータ チャンネルでは使用できますが、v1 はどちらも使用できません。これらの各チャンネルは新機能が追加されると「インプレース」で更新されます。

ベータ チャンネルの機能は、ステーブル チャンネルの機能のスーパーセットである必要があります。アルファ チャンネルの機能は、ベータ チャンネルの機能のスーパーセットである必要があります。

API 機能の廃止

API 要素(フィールド、メッセージ、RPC)は、これ以上使用しないことを示すため、どのチャンネルでも廃止予定にマークされる可能性があります

// A representation of a scroll.
// Books are now preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

廃止予定の API 機能は、アルファからベータへも、ベータからステーブルへも移行しません。つまり、どのチャンネルにも機能の「事前の廃止予定」は到着しません

ベータ チャンネルの機能は、十分な期間廃止予定になった後に削除することができます。推奨期間は 180 日です。アルファ チャネルにのみ存在する機能の場合、廃止予定はオプションで、機能を予告なく削除することができます。削除する前に API のアルファ チャンネルで機能が廃止予定にされた場合、API は同じアノテーションを適用する必要があり、希望する任意の期間使用することができます

リリース ベースのバージョニング

個々のリリースは、その機能が安定したチャネルに組み込まれる前の限られた期間に利用可能になることが予想されるアルファ版またはベータ版のリリースであり、その後、個々のリリースはシャットダウンされます。リリースベースのバージョニング管理戦略を使用する場合、API は各安定性レベルで任意の数の個別のリリースを持つことができます。

アルファとベータのリリースでは、安定性レベルがバージョンに追加され、リリース番号がインクリメントされる必要があります。たとえば、v1beta1v1alpha5 です。API は、コメントなどのドキュメントで、これらのバージョンの時系列を記録する必要があります

アルファまたはベータの各リリースは、下位互換性のある変更によってインプレースで更新される場合があります。ベータ リリースの場合、下位非互換性の更新は、リリース番号をインクリメントして新しいリリースを公開することで実現することが推奨されます。たとえば、現在のバージョンが v1beta1 の場合、次は v1beta2 がリリースされます。

アルファとベータのリリースは、機能がステーブル チャンネルに到達した後には、シャットダウンされる必要があります。アルファ リリースはいつでもシャット ダウンできますが、ベータ リリースではユーザーに合理的な移行期間を与えることが推奨されます。推奨期間は 180 日です。