API 互換性ポリシーおよび非推奨ポリシー

互換性ポリシー

以前のバージョンとの互換性がある変更または非破壊的な変更

既存の API リソースを拡張できるリソース URI の追加

この変更は一般的に安全です。 ただし、この変更では、この変更と競合するコードを生成する可能性がある一般的なクライアント・フレームワークについて考慮する必要があります。 以下の例に、クライアントで生成されるコードを破壊する可能性のある、避ける必要がある変更のタイプを示します。

• API が /v1.0/foo/bar に存在しているものとします。 コード生成プログラムは、クライアント・メソッドとして GetBar を生成する可能性があります。 新しい API が /v1.0/foo/{param} ({param} は任意のストリング) で導入されると、コード生成プログラムが新しいクライアント・メソッドを GetFoo(String param) として生成する可能性があります。 この変更により、GetBar で組み込まれていたロジックが呼び出されなくなるため、クライアントで破壊的な変更が生じる可能性があります。
• 現行パス /v1.0/foo/bar で、クライアントで生成されたコード GetBar および GetBarAsync が生じることがあるものとします。 API /v1.0/foo/Async を追加すると、この生成されたコードと競合します。

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

この変更は、この変更前の要求ペイロードが引き続き存在し、同じように動作するという条件の下で安全です。 既存の API 要求本文に、あるいは照会ストリング・パラメーターとして、オプションのフィールドが追加されることがあります。

オプションの要求ヘッダーの追加

この変更は、この変更前の要求が引き続き同じように応答するという条件の下で安全です。

既存のプロパティーへの許可値の追加

API では、ストリングを使用してプロパティーを表し、制約された値のリストを許可します。 例えば、リソース内の type を文書化して、リソース・タイプの現行リストを列挙できます。 クライアントは、明確に適宜された enum 型の厳密なデシリアライゼーションを使用するのではなく、これらのタイプの汎用ストリングを使用する必要があります。 複数の可能な値を持つプロパティーを受け入れるリソースは、追加の値を許可するように拡張されることがあります。 この新しい値により、対応する新しいプロパティーおよび検証ルールが導入されることがあります。 クライアントは、無効な enum 値が含まれた要求を行ってエラー応答を予期するなどして、存在しない enum 値に対して検証しないようにする必要があります。

存在するプロパティー値では引き続き、既存の動作がサポートされます。 リソース・タイプでの分岐ロジックなどが含まれているクライアント・コードは、以前と同様に機能します。

応答へのオプションのフィールド/ヘッダーの追加

いつでも、オプションのフィールドおよびヘッダーが API 応答に追加されることがあります。 クライアントは、そのような変更に合わせて調整する必要があります。

API 応答でのエラー・メッセージおよびリソース説明の変更

エラー応答内の messageId フィールドは変更不能とみなされ、エラー状態または事例の記述されたリストを常にカバーする必要があります。 このメッセージに関連した説明は変更されることがありますが、ユーザーに対するメッセージの意味は変更されません。

クライアントは、messageDescription 属性に基づいたロジックを構築してはなりません。

エラー・メッセージ ID のスコープの増大

messageId フィールドは、1 つ以上のエラー状態を指します。 この messageId は、いつでも、さらに多くのエラー状態をカバーするように拡張されることがあります。 ただし、そのような拡張は、恣意的ではなく、論理的でなければなりません。 新しいエラー状態は、当該メッセージによってカバーされている既存のエラー状態と密接に関係している必要があります。

レート制限のヘッダーおよびエラー

API の存続期間において API エンドポイントでレート制限が調整されることがあり、これにはバージョンの更新は不要です。

要求が多すぎることを示す HTTP 状況コード 429 を受け取るクライアントは、調整を行う必要があります。

破壊的な変更

API リソース・エンドポイントまたは HTTP メソッドの削除または名前変更

このタイプの変更は、API を使用しているクライアントを破壊するため、許可されません。ただし、強いセキュリティー上のニーズのためにこの変更を行う必要がある場合を除きます。 このような変更を回避するためにあらゆる努力が行われています。

enum 値の削除または名前変更

enum の値は追加されることはありますが、削除することはできません。

フィールドの type の変更

一般的に、フィールドの type は変更してはなりません。 ただし、API 実装で以前の type を受け入れ、以前の type で応答できる場合は、この変更は以前のバージョンとの互換性があるものとみなされます。

既存の要求の可視の動作の変更

以前に要求の結果として特定のアクションまたは応答が生じていた場合、引き続き、同様に動作する必要があります。 唯一の例外は、新しいエラー・メッセージ、HTTP 状況コード、要求フィールド、応答フィールドの形で既存のコントラクトに許可される拡張です。

非推奨ポリシー