バージョン管理された 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 は、安定状態の 上の最初のリリースで、すべてのレガシー（v1.0 と v1.5 ）Atlas Administration
2023-02-01APIリソースを公開します。 Atlas2023 010120230201は、バージョン化された Atlas Administration APIの最初のリリース（ - - および - - ）をサポートしています。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-01 および 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 は新しい trigger バージョンでのみ重大な変更を導入します。 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形式） |
|---|---|---|
| ✓ |
|
| ✓ |
|