バージョン管理された Atlas Administration API の概要
Atlas は、 APIの変更を処理する際に予測可能で一貫したエクスペリエンスを提供するために、バージョン化された Atlas Administration API を提供します。 APIのバージョン管理は、個々のAPIリソース レベルで行われます。 したがって、Atlas が利用しているリソースを廃止する場合は、アクションを実行する必要があります。 Atlas が新しいバージョンをリリースしたリソースを実装していない場合は、アクションを実行する必要はありません。 これにより、新機能の計画、重大な変更の防止、スムーズな統合プロセスを確保すると同時に、本番環境の安定性を維持し、中断を最小限に抑えることができます。
バージョン管理された Atlas Administration API のメリット
新しいバージョンの Atlas Administration API により、プログラムとして Atlas にアクセスする際の全体的なエクスペリエンスが大幅に向上します。 バージョン管理された Atlas Administration API は、次の機能を提供します。
重大な変更と重大でない変更の明確な分離
Atlas は、重大な変更を含むすべての新機能を新しいリソース バージョンで導入しています。 重大じゃない変更を含む機能は、現在の安定したリソース バージョンに引き続き追加されます。 Atlas が新しいリソース バージョンを導入したら、新しいAPIリソース バージョンで開発とテストを行い、完全に非推奨になるまで、現在の安定したリソース バージョンを使用し続けることができます。
延長サポート期間と非推奨期間
Atlas は新しい安定APIリソース バージョンを導入する場合にのみリソース バージョンを非推奨にし、削除します。 Atlas は、本番環境で使用する古いリソース バージョンを最大 12 か月間、古いリソース バージョンをサポートし続けるため、次のバージョンへの移行を計画して実行する時間を提供します。
バージョン管理スキーマ
新しい バージョン管理された Atlas Administration API（v2） 以降、Atlas Administration API のバージョンは、Atlas Administration API リソースのライフサイクルに基づいています。
バージョン管理された Atlas Administration API ライフサイクル
Atlasバージョン管理された AdministrationAPI （v2）以降、Atlas AdministrationAPI Goエンドポイントは、ライフサイクルのstable {0 、deprecated 、sunset ステージを通過し 。
重要
ステージは、リソースの バージョン管理された Atlas Administration API（ v2 ）の Atlas Administration API エンドポイントにのみ適用されます。 これらのステージは、リソースv1.0またはv1.5の Atlas Administration API エンドポイントには影響しません。 Atlas は、2023 年 2 月 1 日の最初のリリースで、すべてのレガシー（v1.0 と v1.5）Atlas Administration API リソースをstable状態で公開します。
stableAtlas は、本番環境で使用するための安定したエンドポイントをサポートします。 Atlas は、すべての安定版エンドポイントに対して変更ログを含むドキュメントを提供します。 この状態のリソース バージョンは、重大じゃない変更でのみ更新されます。
Atlas はエンドポイントに重大な変更を導入すると、新しいリソース バージョンを作成します。 新しいリソース バージョンがリリースされると、Atlas はそのリソースの現在の安定バージョンも自動的に廃止します。 Atlas は、安定状態の
2023-02-01での最初のリリースで、すべてのレガシー（v1.0 と v1.5）Atlas Administration API リソースを公開します。 Atlas は、バージョン化された Atlas Administration API の最初のリリース（2023 年 01 月 01 日および 2023 年 02 月 01 日）を廃止してから 24 か月間サポートします。/clustersリソース バージョン 2023-01-01（および/v1.0/clustersと同等）リソースは、2 年間の非推奨としてマークされています。この状態で Atlas Administration API を使用するには、 リソースに リクエストを送信し、 HTTP Accept ヘッダーとして以下を含めます。
Accept: application/vnd.atlas.<yyyy-mm-dd>+json ここで、
<yyyy-mm-dd>の値は、ドキュメントと変更ログに記載されているエンドポイントのリリース日です。Atlas は406 受け入れられない を 返します リクエストが ヘッダーを省略した、または ヘッダーに存在しないリソース バージョンを指定した場合、エラー応答コードを使用します。
deprecatedAtlas が新しい安定したリソース バージョンを導入すると、Atlas はリソース バージョンを自動的に非推奨にします。 Atlas は、既存のリソースに重大な変更を導入する場合、新しい安定したバージョンをリリースします。
Atlas は、リクエストのレスポンス ヘッダーで非推奨のリソース バージョンについて通知します。 Atlas は、Atlas Administration API の最初のリリース（2023 年 01 月 1 日および 2023 年 02 月 01 日）を廃止してから 24 か月間サポートします。 その後、Atlas は、自動的に削除される前に、本番環境で使用する将来の非推奨のリソース バージョンを 12 か月間サポートします。
例
以下は、将来削除が予定されている非推奨のリソースに対するリクエストの応答ヘッダーの例です。
Deprecation: Wed, 1 Feb 2023 00:00:00 GMT Sunset: Sun, 1 Jun 2025 00:00:00 GMT リクエストは、古いリソース バージョンが削除されるまで、引き続きエンドポイントの古いリソース バージョンにリクエストを送信し続けます。 ただし、古いリソース バージョンが削除されたときに中断を軽減するために、最新のリソース バージョンにできるだけ早く移行する必要があります。 新しいリソース バージョンへの移行の詳細については、「 新しいバージョンの Atlas Administration API への移行 」を参照してください。
sunsetAtlas は 1 年間の非推奨後に、リソース バージョンを自動的に削除します。 削除されたリソース バージョンに リクエストを送信すると、Atlas は410 Gone を返します エラー応答コード。
例
次の例では、リソースのライフサイクルとバージョン管理への影響を示しています。
前の図には、次の内容が示されています。
リリース日 | リリースの詳細 | API ライフサイクル |
2023-06-01 | Versioned API でのリソースの初めてのリリース。 非推奨期間は 12 か月です。 |
|
2024-06-01 | 新しいリソース バージョンが作成され、古いバージョンは自動的に非推奨になります。 |
|
2025-01-01 | 新しい安定バージョンを作成し、日も短くなります |
|
API エンドポイント
レガシーのバージョン化されていない Atlas Administration API エンドポイントに対し、Atlas は新しい重大な変更を同じバージョンで導入しました。 バージョン管理された Atlas Administration API（v2）以降、Atlas は新しいリソース バージョンでのみ重大な変更を導入します。 Atlas は、既存のstableバージョンに重大でない変更を引き続き導入します。 リソースのリリース日を使用して、特定のバージョンのバージョン管理された Atlas Administration API（v2）エンドポイントにリクエストを送信します。
次の表は、レガシーAPIエンドポイントのバージョン、そのバージョンに対応するバージョン管理された Atlas Administration API（v2）エンドポイントがあるかどうか、および バージョン化された Atlas Administration API（v2）リソースのリリース日を示しています。 バージョン化されていない Atlas Administration API の v1.0 に相当するものは、バージョン化された Atlas Administration API では2023-01-01によって表されることに注意してください。これは現在非推奨です。
バージョン番号 | v2 でサポートされていますか？ | v2 リソース バージョン（ yyyy-mm-dd形式） |
|---|---|---|
v1.0 | ✓ | 2023-01-01 |
v1.5 | ✓ | 2023-02-01 |