互換性とバージョン管理ポリシー

このドキュメントで、バージョンとは、RESTリソースのデータ構造定義および機能の特定の表現を意味します。互換性とは、クライアントがサービスの特定のバージョンで動作できることを意味します。下位互換性とは、APIの特定のメジャーバージョンを対象に作成されたクライアントが、同じメジャーバージョン内の将来のマイナーバージョンでも、修正を加えられずに機能し続けられることを意味します。

バージョン管理

Amazon Ads APIのRESTリソースは、major.minor形式を使用して単独でバージョン管理されています。この形式はそれぞれ「3.0」のような整数値です。

現在、ほとんどのリソースはバージョンを1つ持っています。リソースの別のバージョンが追加されると、クライアントはAcceptリクエストヘッダーフィールドを使用して、特定のバージョンの表現をリクエストします。指定されたとおりのバージョンがサービスでサポートされている場合は、常にそのバージョンのリソースが返されます。

注

今後、特定のバージョンをリクエストしないクライアントは最新バージョンを受け取るようになります。廃止されたバージョンをリクエストしたクライアントは、互換性のある最新バージョンを受け取ります。この動作の実装に関するお知らせは、リリースノートをご覧ください。

互換性

メジャーバージョン内においては、Amazon Ads APIサービスのリソースに下位互換性があることが保証されています。下位互換性は、安定したリソース表現を使用することで確保されます。

安定したリソース表現には、以下のような特性があります。

• リソース表現で定義されたプロパティは、名前と値のタイプが変わりません。値のタイプがarrayの場合、arrayの使用可能な値セットは増えることはあっても、減ることはありません。値のタイプがobjectの場合は、objectも安定した表現です。
• プロパティの定義は、メジャーバージョン内では一貫していて、変更されることはありません。
• 新しいマイナーバージョンのリソース表現で新しいプロパティが定義されることはありますが、新しいプロパティによって以前に定義されたプロパティの意味が調整または変更されることはありません。
• 値のタイプで暗黙的な順序が定義されている場合、その順序と意味はマイナーバージョン内で一貫しており、変更されません。

以下の状況では、Amazon Ads APIが安定したリソース表現を返さないことがあります。

• 安定したリソース表現を破壊する必要のある法的な問題が発生した場合。
• 安定したリソース表現を破壊することでしか修正できない致命的なバグが発見された場合。
• 安定したリソース表現を破壊することでしか緩和できない、重大なセキュリティ上の欠陥が発見された場合。

安定したリソース表現が返されない場合、Amazon Ads APIはクライアントに変更を通知し、クライアントと協力して、安定したリソース表現の新しいバージョンに移行します。

廃止

Amazon Ads APIは、メジャーバージョンの廃止について、遅くとも6か月前までにはクライアントに通知するよう最大限努めています。Amazon Ads APIは、クライアントの最新バージョンへの移行を支援するための移行ガイダンスを提供します。

法的な問題、致命的なバグ、または重大なセキュリティ上の欠陥が原因で安定したリソース表現が返されなくなった場合、関連する安定したリソース表現は早急に廃止されます。