版本化 Atlas Administration API 概述
Atlas 提供版本化的 Atlas Administration API，以便在处理 API更改时提供可预测且一致的体验。 API版本控制发生在单个API资源级别。 因此，如果 Atlas 弃用您正在使用的资源，您需要采取操作。如果您尚未实施 Atlas 已发布新版本的资源，则无需执行任何操作。 这使您能够规划新功能，防止破坏性变更 (breaking change)，确保集成过程顺利进行，同时保持生产环境的稳定性并最大限度地减少中断。
版本化 Atlas Administration API 的优势
新版本的 Atlas Administration API 在以编程方式访问 Atlas 方面提供了显着更好的整体体验。 版本化的 Atlas Administration API 提供以下功能：
破坏性变更 (breaking change)和非破坏性变更 (non-breaking change)的明确区分
Atlas 在新的资源版本中引入了所有新功能和破坏性变更 (breaking change)。包含非破坏性变更 (non-breaking change)的功能将继续添加到当前的稳定资源版本中。当 Atlas 推出新的资源版本时，您可以在新的API资源版本上进行开发和测试时，继续使用当前的稳定资源版本，直到其完全弃用。
延长支持期和弃用期
Atlas 仅在引入新的稳定API资源版本时才会弃用然后删除资源版本。 Atlas 将继续支持旧资源版本在生产环境中使用长达十二个月，以便您有时间规划和执行到下一个版本的迁移。
版本控制模式
从新的版本化 Atlas Administration API (v2) 开始，Atlas Administration API 版本基于 Atlas Administration API 资源的生命周期。
版本化 Atlas Administration API 生命周期
从版本化 Atlas Administration API (v2) Go，Atlas Administration API 端点会经历生命周期中的 stable 、 deprecated和sunset阶段。
重要
这些阶段仅适用于资源的版本化 Atlas Administration API ( v2 ) 中的 Atlas Administration API 端点。 这些阶段不会影响资源v1.0或v1.5中的 Atlas Administration API 端点。 Atlas 在 2023 年 2 月 1 日发布的首个版本中以stable状态公开所有旧版（v1.0 和 v1.5）Atlas Administration API 资源。
stableAtlas支持在生产环境中使用稳定的端点。 Atlas为所有稳定端点提供文档，其中包括变更日志。 处于这种状态的资源版本只会进行非重大更改的更新。
当 Atlas 对端点引入破坏性变更 (breaking change)时，它会创建新的资源版本。发布新的资源版本时，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的等效项）资源被标记为已弃用，并具有两年弃用窗口。要在此状态下使用 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 将在弃用后的 24 个月内支持 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。
sunsetAtlas 会在弃用一年后自动删除资源版本。 如果您向已删除的资源版本发送请求，Atlas 将返回410 Gone 错误响应代码。
例子
以下示例说明了资源的生命周期及其对版本控制的影响。
上图显示了以下内容：
发布日期 | 版本详情 | API 生命周期 |
2023-06-01 | 版本化 API 中资源的首次发布。 其弃用期为 12 个月。 |
|
2024-06-01 | 创建新的资源版本，旧版本将被自动弃用。 |
|
2025-01-01 | 已创建新的稳定版本，且日落时间较短 |
|
API端点
对于传统的未版本控制的 Atlas Administration API 端点，Atlas 在同一版本中引入了新的重大更改。 从版本化的 Atlas Administration API (v2) 开始，Atlas 仅在新的资源版本中引入破坏性变更 (breaking change)。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格式） |
|---|---|---|
| √ |
|
| √ |
|