バージョン管理された Atlas Administration API の概要

重大な変更と重大でない変更の明確な分離

Atlas は、重大な変更を含むすべての新機能を新しいリソースバージョンで導入しています。現在の安定したリソースバージョンには、重大じゃない変更を含む機能が引き続き含まれています。Atlas が新しいリソースバージョンを導入したら、新しいAPIリソースバージョンで開発とテストを行い、完全に非推奨になるまで、現在の安定したリソースバージョンを使用し続けることができます。

延長サポート期間と非推奨期間

Atlas は新しい安定APIリソースバージョンを導入する場合にのみリソースバージョンを非推奨にし、削除します。Atlas は、本番環境で使用する古いリソースバージョンを最大 12 か月間サポートし続けるため、次のバージョンへの移行を計画および実行する時間を確保できます。

バージョン管理された Atlas Administration API ライフサイクル

バージョン管理された Atlas Administration API （v2）以降、Atlas Administration APIエンドポイントは、ライフサイクルの preview、stable、deprecated、sunset ステージを通過します。

preview

Atlas は、評価、テスト、開発目的でのみこの状態のエンドポイントをサポートします。プレビューのエンドポイントには重大な変更と重大でない変更が含まれる可能性があるため、実稼働環境のプレビューで Atlas Administration APIエンドポイントを使用しないでください。プレビュー版の Atlas Administration APIエンドポイントの非推奨ウィンドウも約 30 日以下で、その後エンドポイントは stable または deprecated 状態に移行する可能性があります。

プレビューでAPIエンドポイントを使用するには、リソースにリクエストを送信し、次のHTTPヘッダーを含めます。

Accept: application/vnd.atlas.preview+json

stable

Atlas は、本番環境で使用するための安定したエンドポイントをサポートします。Atlas は、すべての安定版エンドポイントに対して 変更ログ を含むドキュメントを提供します。この状態のリソースバージョンは、重大じゃない変更でのみ更新されます。

Atlas はエンドポイントに重大な変更を導入すると、新しいリソースバージョンを作成します。新しいリソースバージョンがリリースされると、Atlas はそのリソースの現在の安定バージョンも自動的に削除します。Atlas はすべてのレガシー（v1.0および v1.5）安定状態の 2023-02-01 上の最初のリリースの Atlas Administration APIリソース。Atlas は、バージョン化された Atlas Administration APIの最初のリリース（ 2023-01 -01 および2023 -02 -0124 ）をサポートしています。/clustersリソースバージョン 2023-01-01（および /v1.0/clusters と同等）リソースは、2 年間の非ウィンドウとしてマークされていることに注意してください。

この状態で Atlas Administration API を使用するには、 リソースに リクエストを送信し、 HTTP Accept ヘッダーとして以下を含めます。

Accept: application/vnd.atlas.<yyyy-mm-dd>+json

ここで、 <yyyy-mm-dd>の値は、ドキュメントと変更ログに記載されているエンドポイントのリリース日です。

406リクエストで が省略されている場合、または ヘッダーに存在しないリソースバージョンが指定されている場合、Atlas は 「受け入れられません」 の応答コードを返します。

deprecated

Atlas が新しい安定したリソース バージョンを導入すると、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への移行」を参照してください。

sunset

Atlas は 1 年間の非推奨後に、リソースバージョンを自動的に削除します。削除されたリソースバージョンにリクエストを送信すると、Atlas は410 Gone エラー応答コードを返します。

認証済みAPIリソースのライフサイクル

次の例では、リソースのライフサイクルとバージョン管理への影響を示しています。

クリックして拡大します

前の図には、次の内容が示されています。

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によって表されることに注意してください。これは現在非推奨です。