版本化 Atlas Administration API 概述

破坏性变更 (breaking change)和非破坏性变更 (non-breaking change)的明确区分

Atlas在新的资源版本中引入了所有具有重大更改的新功能。当前的稳定资源版本仍包含包含非重大更改的功能。当Atlas推出新的API资源版本时，您可以在新的API资源版本上进行开发和测试时，继续使用当前的稳定资源版本，直到其完全弃用。

延长支持期和弃用期

Atlas仅在引入新的稳定API资源版本时才会弃用然后删除资源版本。 Atlas会继续支持旧资源版本在生产环境中使用长达十二个月，让您有时间规划和执行到下一个版本的迁移。

版本化 Atlas Administration API 生命周期

从版本化 Atlas Administration API (v2) Go，Atlas Administration API 端点会经历生命周期中的 stable 、 deprecated和sunset阶段。

stable

Atlas支持在生产环境中使用稳定的端点。 Atlas为所有稳定端点提供文档，其中包括 变更日志。处于此状态的资源版本仅在进行非重大更改时进行更新。

当Atlas对端点引入重大更改时，它会创建新的资源版本。发布新的资源版本时， Atlas还会自动弃用该资源的当前稳定版本。 Atlas在 2023-02-01 的第一个稳定状态发布中公开了所有旧版（v1.0 和 v1.5） Atlas Administration API资源。 Atlas在版本化Atlas Administration API 弃用后的 24 个月内，为 Atlas Administration API的第一个发布（2023-01-01 和 2023-02-01）提供支持。请注意，/clusters资源版本 2023-01-01（以及 /v1.0/clusters 的等效版本）资源被标记为已弃用，并具有两年弃用窗口。

要在此状态下使用 Atlas Administration API，请向资源发送请求，并包含以下内容作为 HTTP Accept 标头：

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

其中<yyyy-mm-dd>的值是文档和变更日志中列出的端点的发布日期。

Atlas 返回406 不可接受 错误响应代码（如果请求省略或指定标头中不存在的资源版本）。

deprecated

当 Atlas 引入新的稳定资源版本时，Atlas 会自动弃用资源版本。 Atlas 发布新的稳定版本，对现有资源进行破坏性变更 (breaking change)。

Atlas会在请求的响应标头中通知您已弃用的资源版本。在弃用后， Atlas在Atlas Administration API的第一个版本（2023-01-01 和 2023-02-01）内支持 24 个月。随后， Atlas支持任何未来已弃用的资源版本在生产环境中使用十二个月，然后自动将其删除。

例子

以下显示了对计划在将来删除的已弃用资源发出请求的示例响应标头。

Deprecation: Wed, 1 Feb 2023 00:00:00 GMT
Sunset: Sun, 1 Jun 2025 00:00:00 GMT

您可以继续向端点的旧资源版本发送请求，直到它们被删除。但是，您应尽快迁移到最新的资源版本，以避免删除旧资源版本时造成中断。要学习；了解有关迁移到新资源版本的更多信息，请参阅迁移到新版本的Atlas Administration API。

sunset

Atlas 会在弃用一年后自动删除资源版本。 如果您向已删除的资源版本发送请求，Atlas 将返回410 Gone 错误响应代码。

例子

以下示例说明了资源的生命周期及其对版本控制的影响。

上图显示了以下内容：

发布日期	版本详情	API 生命周期
2023-06-01	版本化 API 中资源的首次发布。 其弃用期为 12 个月。	#stable: application/vnd.atlas.2023-06-01+json #deprecated: none #sunset: none
2024-06-01	创建新的资源版本，旧版本将被自动弃用。	#stable: application/vnd.atlas.2024-06-01+json #deprecated: application/vnd.atlas.2023-06-01+json #sunset: none
2025-01-01	已创建新的稳定版本，且日落时间较短	#stable: application/vnd.atlas.2025-01-01+json #deprecated: application/vnd.atlas.2024-12-01~preview+json application/vnd.atlas.2024-06-01+json #sunset: application/vnd.atlas.2023-06-01+json

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表示，后者现已弃用。