互換性

このページでは、バージョニングセクションに示されている、互換性を損なう変更と互換性を損なわない変更のリストについて、より詳細に説明します。

何が互換性を損なう（互換性のない）変更としてみなされるかは、必ずしも明確ではありません。ここでのガイダンスは、あらゆる可能な変更の包括的なリストではなく、指針として扱うことが推奨されます。

ここにリストされているルールは、クライアントの互換性にのみ関係しています。API プロデューサーは、実装の詳細の変更を含め、デプロイについて独自の要件を認識していることが期待されます。

一般的な目的は、新しいマイナーバージョンやパッチに更新するサービスによってクライアントが破壊されないようにすることです。考慮する破壊には次の種類があります。

ソースの互換性: 1.0 に対して書かれたコードを 1.1 に対してコンパイルできない
バイナリ互換性: 1.0 に対してコンパイルされたコードを 1.1 クライアントライブラリに対してリンクまたは実行できない（厳密な詳細はクライアントプラットフォームによって異なります。これはさまざまな状況で変わることがあります）
ワイヤの互換性: 1.0 に対して構築されたアプリケーションが 1.1 サーバーと通信できない
セマンティックの互換性: すべてが実行されるが、意図しない結果や意外な結果となる

言い換えると、古いクライアントが、同じメジャーバージョン番号内の新しいサーバーに対して動作できる必要があり、新しいマイナーバージョンに更新（新しい機能を活用するためなどに）したくなったときに、簡単に更新できる必要があります。

注: v1.1 や v1.0 などのバージョン番号を指す場合、具体的なバージョンではない論理バージョン番号を指しています。これらは単に変更を説明しやすくするためのものです。

プロトコルベースの理論的な考慮事項に加えて、生成されたコードと手書きコードの両方を含むクライアントライブラリが存在することによる実際的な考慮事項があります。検討している変更について、可能な場合は常に、新しいバージョンのクライアントライブラリを生成し、それらがテストに引き続き合格することを確認するテストを実施してください。

以下の説明では、proto メッセージを 3 つのカテゴリに分類します。

リクエストメッセージ（GetBookRequest など）
レスポンスメッセージ（ListBooksResponse など）
リソースメッセージ（Book など、他のリソースメッセージ内で使用されるメッセージを含む）

これらのカテゴリには異なるルールがあります。リクエストメッセージはクライアントからサーバーに送信されるのみで、レスポンスメッセージはサーバーからクライアントに送信されるのみですが、リソースメッセージは通常は両方向に送信されます。特に、更新可能なリソースは、読み取り / 変更 / 書き込みサイクルの観点から考慮する必要があります。

下位互換性のある（互換性を損なわない）変更

API サービス定義への API インターフェースの追加

プロトコルの観点からは、これは常に安全です。唯一の注意点は、手書きコード内の新しい API インターフェース名がクライアントライブラリですでに使用されている可能性があることです。新しいインターフェースが既存のインターフェースと関連性がない場合、この可能性は低くなります。新しいインターフェースが既存のインターフェースの簡易版である場合は、競合が発生する可能性が高くなります。

API インターフェースへのメソッドの追加

クライアントライブラリですでに生成されているメソッドと競合するメソッドを追加しない限り、このことは問題ありません。

互換性を損なう可能性があるのは、次の例のような場合です。GetFoo メソッドを使用している場合、C# コードジェネレータによって、すでに GetFoo と GetFooAsync メソッドが生成されています。このため、クライアントライブラリの観点からは、API インターフェースに GetFooAsync メソッドを追加することは、互換性を損なう変更になります。

メソッドへの HTTP バインディングの追加

バインディングによって曖昧さが発生しないと仮定すると、以前に拒否していた URL にサーバーが応答するようにすることは安全です。これは、既存のオペレーションに新しいリソース名パターンを適用するときに行われる可能性があります。

リクエストメッセージへのフィールドの追加

リクエストフィールドの追加は、フィールドを指定しないクライアントが新しいバージョンでも古いバージョンと同じように扱われる限り、互換性を損なうことはありません。

最も明白な正しくない例として、ページ分けがあります。API の v1.0 にコレクションのページ分けが含まれていない場合、デフォルトの page_size が無限として扱われない限り、V1.1 にコレクションのページ分けを追加することはできません（これは一般的には良くないアイデアです）。それ以外の場合は、単一のリクエストから完全な結果を得ることを想定している v1.0 クライアントが、コレクションにより多くのリソースが含まれているという認識なしに、省略された結果を受け取ることがあります。

レスポンスメッセージへのフィールドの追加

リソース以外のレスポンスメッセージ（ListBooksResponse など）は、他のレスポンスフィールドの動作を変更しない限り、クライアントを中断することなく展開できます。以前にレスポンスで入力されていたフィールドは、冗長性が導入されても、引き続き同じセマンティクスで入力されます。

たとえば、1.0 のクエリレスポンスには、重複のために一部の結果が省略されたことを示す contained_duplicates のブールフィールドがあるとします。1.1 では、duplicate_count フィールドでより詳細な情報が提供されています。1.1 の観点から見ると冗長になりますが、contained_duplicates フィールドには、引き続き値が入力されていることが必須です。

列挙型への値の追加

リクエストメッセージでのみ使用される列挙型は、自由に拡張して新しい要素を含めることができます。たとえば、リソースビューパターンを使用すると、新しいビューを新しいマイナーバージョンに追加できます。クライアントはこの列挙型を受け取る必要はないため、処理しない値を認識する必要はありません。

リソースメッセージとレスポンスメッセージについては、デフォルトの前提として、クライアントは認識していない列挙値を処理する必要があります。ただし、API プロデューサーは、新しい列挙要素を正しく処理するアプリケーションを作成することは難しい場合があることを認識する必要があります。API オーナーは、不明な列挙値が発生した場合のクライアントの予想される動作をドキュメント化することが推奨されます。

Proto3 では、クライアントは認識していない値を受け取り、同じ値を維持しながらメッセージを再シリアル化できるため、読み取り / 変更 / 書き込みサイクルが中断されません。JSON 形式では、値の「名前」が不明な数値を送信することが許容されますが、サーバーでは、通常、クライアントが特定の値を実際に認識しているかどうかはわかりません。このため、JSON クライアントは以前は不明だった値を受け取ったことを認識できますが、認識するのは名前と数値のどちらか一方のみです。両方を認識することはありません。同じ値を読み取り / 変更 / 書き込みサイクルでサーバーに戻した場合、サーバーは両方の形式を認識する必要があるため、そのフィールドは変更されません。

出力専用リソースフィールドの追加

サーバーによって提供されるのみの、リソースエンティティ内のフィールドを追加できます。サーバーはリクエスト内のクライアント提供の値が有効であることを検証できますが、値が省略されたかどうかは検証する必要があります。

下位互換性のない（互換性を損なう）変更

サービス、フィールド、メソッド、列挙値の削除や名前変更

基本的に、クライアントコードによって参照される可能性のあるものについて、削除したり名前を変更したりすることは互換性を損なう変更となり、メジャーバージョンを増加させる必要があります。古い名前を参照するコードにより、一部の言語（C# や Java など）ではコンパイル時にエラーが発生し、他の言語では実行時にエラーが発生したり、データが失われたりする可能性があります。送信形式の互換性はここでは関係ありません。

HTTP バインディングの変更

ここでの「変更」は、事実上「削除と追加」です。たとえば、PATCH をサポートする必要があるが、公開版では PUT がサポートされている場合や、誤ったカスタム動詞名を使用した場合、新しいバインディングを追加できますが、サービスメソッドを削除することが互換性を損なう変更になるのと同じ理由から、古いバインディングを削除することはできません。

フィールドのタイプの変更

新しい形式が送信形式に対応している場合でも、これによりクライアントライブラリの生成コードが変更される可能性があるため、メジャーバージョンを増加させる必要があります。コンパイル済みの、静的に型指定された言語では、コンパイル時にエラーが発生しやすくなります。

リソース名の形式の変更

リソース名は変更できません。つまり、コレクション名は変更できません。

互換性を損なうほとんどの変更とは異なり、このことはメジャーバージョンにも影響します。クライアントが v1.0 で作成されたリソースに v2.0 でアクセスすることが予想される場合、またはその逆の場合、両方のバージョンで同じリソース名を使用するようにします。

より詳細には、次の理由から、有効なリソース名のセットも変更しないことが推奨されます。

より限定的になると、以前は成功していたリクエストが失敗するようになります。
以前にドキュメント化されたものよりも限定的でなくなった場合、以前のドキュメント化に基づいて前提条件を設定しているクライアントが破損する可能性があります。クライアントは、多くの場合、許可された文字セットと名前の長さに厳密な方法で、他の場所にリソース名を格納します。または、クライアントはドキュメントに従うために独自のリソース名検証を実行する可能性があります（たとえば、より長い EC2 リソース ID を使用できるようにした際に、Amazon はお客様に多くの警告を示し、移行期間を設けました）。

このような変更は、proto のドキュメントによってのみ示されるので注意してください。このため、破損のために CL を見直すときは、非コメントの変更を見直すだけでは不十分です。

既存のリクエストの可視動作の変更

動作が明示的にサポートされていない場合やドキュメント化されていない場合でも、クライアントは多くの場合、API の動作とセマンティクスに依存します。したがって、ほとんどの場合、API データの動作やセマンティクスを変更することは、ユーザーからは破壊とみなされます。動作が暗号的に隠されていない場合は、ユーザーがその動作を見つけて依存すると想定することが推奨されます。

この理由から、ユーザーが独自のトークンを作成し、トークンの動作が変更されたときに破壊されないように、（データの内容に関係なく）ページ設定トークンを暗号化することをおすすめします。

HTTP 定義での URL 形式の変更

上記のリソース名の変更の他に、ここでは 2 種類の変更について検討します。

カスタムメソッド名: リソース名の一部ではありませんが、カスタムメソッド名は REST クライアントによって送信される URL の一部です。カスタムメソッド名を変更しても gRPC クライアントは破損しませんが、パブリック API は REST クライアントを持っていると想定する必要があります。
リソースパラメータ名: v1/shelves/{shelf}/books/{book} から v1/shelves/{shelf_id}/books/{book_id} への変更は、置き換えられたリソース名には影響しませんが、コード生成に影響する可能性があります。

リソースメッセージへの読み取り / 書き込みフィールドの追加

クライアントは多くの場合、読み取り / 変更 / 書き込みオペレーションを実行します。ほとんどのクライアントは、認識しないフィールドに値を提供しません。特に proto3 ではこれをサポートしていません。プリミティブ型ではなくメッセージ型の欠落フィールドがある場合、これらのフィールドに更新が適用されないことを指定できますが、これにより、そのようなフィールド値をエンティティから明示的に削除することが難しくなります。 proto3 では、int32 フィールドを明示的に 0 を指定することと指定しないことには違いがないため、プリミティブ型（string と bytes を含む）を単純にこのように処理することはできません。

すべての更新がフィールドマスクを使用して実行される場合は、このことは問題ではありません。これは、クライアントが認識しないフィールドはクライアントによって暗黙的に上書きされないためです。ただし、この決定は通常の API とは異なります。ほとんどの API では「リソース全体」の更新が許可されます。

バージョニング

ディレクトリ構造

互換性