バージョニング

1 つの API サービスにより複数の API インターフェースが提供される可能性があるため、API のバージョニング方式は、API サービスレベルではなく API インターフェース レベルで適用されます。便宜上、以降では、API という用語は API インターフェースを指します。

ネットワーク API では、セマンティック バージョニングを使用することが推奨されます。バージョン番号 MAJOR.MINOR.PATCH が指定されている場合、次のものが増加されます。

  1. 互換性のない API の変更を行う場合には、MAJOR バージョン
  2. 下位互換性のある方法で機能を追加する場合には、MINOR バージョン
  3. 下位互換性のあるバグ修正を行う場合には、PATCH バージョン

メジャー バージョン番号の指定に適用されるルールは、API のバージョンに応じて異なります。

  • バージョン 1(v1)の API の場合、このメジャー バージョン番号を、プロト パッケージ名の最後のコンポーネント(google.pubsub.v1 など)としてエンコードすることが推奨されます。可能性は低いものの、互換性を損なう変更が行われないと予測される、明らかに安定した型とインターフェースがパッケージに含まれている場合、メジャー バージョンをプロト パッケージ名から省略することが可能です(google.protobufgoogle.longrunning など)。
  • v1 以外の API のすべてのバージョンでは、メジャー バージョン番号をプロト パッケージ名の最後のコンポーネントとしてエンコードする必要があります。たとえば、google.pubsub.v2 のようにします。

アルファやベータなどの一般提供前のリリースでは、バージョン番号に接尾辞を付けることをおすすめします。接尾辞は、プレリリース バージョン名(アルファやベータなど)と、任意のプレリリース バージョン番号で構成することが推奨されます。

バージョンの移行の例:

バージョン プロト パッケージ 説明
v1alpha v1alpha1 v1 アルファ リリース。
v1beta1 v1beta1 v1 ベータ 1 リリース。
v1beta2 v1beta2 v1 の 2 回目のベータリリース。
v1test v1test ダミーデータによる内部テストリリース。
v1 v1 v1 メジャー バージョン、一般提供。
v1.1beta1 v1p1beta1 v1 にマイナー変更を加えた最初のベータリリース。
v1.1 v1 v1.1 リリースへのマイナー更新。
v2beta1 v2beta1 v2 ベータ 1 リリース。
v2 v2 v2 のメジャー バージョン、一般提供。

マイナー番号とパッチ番号は、API の構成とドキュメントに反映することが推奨され、プロト パッケージ名でエンコードしない必要があります。

注: 現時点で、Google API プラットフォームでは、マイナー バージョンとパッチ バージョンはネイティブにサポートされていません。API メジャー バージョンごとに、ドキュメント ライブラリとクライアント ライブラリのセットは 1 つのみです。API オーナーは、API のドキュメントとリリースノートを使用して手動でドキュメント化する必要があります。

API の新しいメジャー バージョンは、同じ API の以前のメジャー バージョンに依存していない必要があります。他の API に関連付けられる依存性と安定性のリスクを理解したうえで、API が他の API に依存することは可能です。安定した API バージョンは、他の API の安定した最新のバージョンにのみ依存する必要があります。

単一のクライアント アプリケーション内で、同じ API の異なるバージョンが一定期間同時に動作できる必要があります。これは、クライアントが API の古いバージョンから新しいバージョンにスムーズに移行するために役立ちます。

古い API バージョンは、そのサポート期間が終了した後にのみ削除する必要があります。

多くの API で共有される一般的で安定したデータ型(日付や時刻など)は、個別のプロト パッケージで定義することが推奨されます。互換性を損なう変更が必要になった場合は、新しいタイプ名か、新しいメジャー バージョンのパッケージ名を導入する必要があります。

下位互換性

下位互換性のある変更の判断基準が難しい場合があります。

次のリストは、クイック リファレンスの開始点ですが、ご不明な点がある場合、詳細については、設計の互換性に関するページをご覧ください。

下位互換性のある(互換性を損なわない)変更

  • API サービスへの API インターフェースの追加
  • API インターフェースへのメソッドの追加
  • メソッドへの HTTP バインディングの追加
  • リクエスト メッセージへのフィールドの追加
  • レスポンス メッセージへのフィールドの追加
  • 列挙型への値の追加
  • 出力専用リソース フィールドの追加

下位互換性のない(互換性を損なう)変更

  • サービス、インターフェース、フィールド、メソッド、列挙値の削除や名前変更
  • HTTP バインディングの変更
  • フィールドのタイプの変更
  • プロト フィールド番号の変更
  • リソース名の形式の変更
  • 既存のリクエストの可視動作の変更
  • HTTP 定義での URL 形式の変更
  • リソース メッセージへの読み取り / 書き込みフィールドの追加
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...