微版本规范

本文档旨在提供关于如何在 OpenStack REST API 中使用微版本的指导。

微版本允许在引入 API 变更的同时，让客户端能够发现这些变更。根据与服务器的协商，客户端调整其行为以与服务器正确协作。

版本控制

API 的版本控制应采用单一的单调递增计数器，格式为 X.Y，并遵循以下约定

• 只有在进行重大的向后不兼容的 API 变更，并且影响整个 API 时，才应更改 X。也就是说，这是一种非常罕见的递增方式。在以下情况下应更改 X。
  • 多个端点被其他端点取代
  • API 消费者工作流程的重大变化
• 当您对 API 进行任何更改时，应更改 Y。请注意，这包括语义更改，这些更改可能不会影响输入或输出格式，甚至不会源于 API 代码层。我们在版本控制系统中不区分向后兼容和向后不兼容的更改。但是，将在文档中明确说明哪些是向后兼容的更改，哪些是不兼容的更改。

注意

请注意，这些版本号不遵循 语义版本控制 的规则。

存在最小值和最大值版本，用于描述服务器可以理解的内容。最小值和最大值版本分别是支持的最旧版本和最新版本。因此，客户端可以在同一服务器上的每个 API 调用中指定支持范围内的不同版本。当支持旧客户端的负担过大时，可以增加最小值版本。增加最小值版本意味着破坏旧客户端，这种情况也很少发生。

每个版本都包含自引入最小值版本以来的所有更改。不可能在同一请求中请求在微版本 X.Y 中引入的功能，而不接受 X.Y 之前的全部更改。例如，您不能请求在微版本 2.100 中引入的功能，而不接受在微版本 2.99 及更早版本中引入的向后不兼容的更改。

客户端交互

客户端通过以下方法指定他们想要使用的 API 版本，即一个新的标头

OpenStack-API-Version: [SERVICE_TYPE] [VERSION_STRING]

例如，Keystone 将使用以下头部

OpenStack-API-Version: identity 2.114

从概念上讲，这就像 accept 头部一样。

客户端应期望服务器具有以下行为

• 如果未提供 OpenStack-API-Version 头部，则表现得好像指定了最小支持版本。
• 如果发送了 OpenStack-API-Version 头部，但值与当前服务不匹配，则表现得好像指定了最小支持版本。
• 如果发送了 OpenStack-API-Version 头部，服务类型匹配，并且版本采用版本字符串的形式，则使用指示的版本响应 API。如果版本超出支持的版本范围，并且不是字符串latest（如下所述），则返回 406 Not Acceptable，并包含支持的最小值和最大值版本的响应体。
• 头部 OpenStack-API-Version 的值是OpenStack-API-Version头部是[SERVICE_TYPE] [VERSION_STRING]。VERSION_STRING 必须匹配 “^([1-9]d*).([1-9]d*|0)$”。如果 VERSION_STRING 不匹配正则表达式模式，则返回 400 Bad Request，并带有符合错误指南 Errors 的错误响应体。
• 如果发送了 OpenStack-API-Version 头部，服务类型匹配，并且版本设置为特殊关键字latestlatest

警告

Thelatest则表现得好像指定了最大版本。此值主要用于集成测试，并且由于微版本不遵循 semver，因此向后兼容性无法保证，不建议在客户端代码中依赖它。客户端应始终需要特定的微版本，但将其限制为它在当时理解的版本范围。

始终在响应中返回两个额外的标头

OpenStack-API-Version: [SERVICE_TYPE] version_number
Vary: OpenStack-API-Version

第一个头部指定了执行的 API 的版本号。一个例子

OpenStack-API-Version: compute 2.22

TheVary头部用作缓存代理和用户代理的提示，表明响应也依赖于 OpenStack-API-Version，而不仅仅是主体和查询参数。有关详细信息，请参阅 RFC 7231。

注意

服务器必须准备好处理多个 OpenStack-API-Version 头部。当设计用于处理多个服务的客户端始终发送它认为需要的头部时，可能会发生这种情况。大多数 Python 框架会通过将头部的值设置为所有匹配的头部的值（用“,”（逗号）分隔）来处理这种情况。例如compute 2.11,identity 2.114.

注意

一个名为 microversion-parse 的 Python 库可用于帮助服务器端处理微版本头部，包括本文档中描述的新样式和以前的形式。

版本发现

每个服务的版本 API 应返回最小值和最大值版本。客户端使用这些值来发现支持的 API 版本。如果服务决定提高将支持的最小值版本，它还应返回下一个最小值版本，以及当前最小值版本保证受支持的日期。如果没有任何计划更改最小值微版本，则应省略下一个最小值版本和支持日期。

计划提高其最小支持版本的服务的版本响应如下所示

GET /
{
     "versions": [
        {
            "id": "v2.1",
            "links": [
                  {
                    "href": "https://:8774/v2/",
                    "rel": "self"
                }
            ],
            "status": "CURRENT",
            "max_version": "2.42",
            "min_version": "2.1",
            "next_min_version": "2.13",
            "not_before": "2019-12-31"
        },
   ]
}

注意

Thelinks符合 Links 指南。

“max_version” 是支持的最大版本；“min_version” 是支持的最小版本；“next_min_version” 是计划的下一个最小版本；“not_before” 是最小值不会更改的日期（ISO YYYY-MM-DD 格式）。请注意，这并不要求在该日期提高最小值；任何时候之后都可以发生这种情况。它旨在让操作员了解他们需要更改工具以支持它的速度。

如果没有任何计划更改最小值版本，则响应可以省略“next_min_version”和“not_before”值。这样的响应如下所示

GET /
{
     "versions": [
        {
            "id": "v2.1",
            "links": [
                  {
                    "href": "https://:8774/v2/",
                    "rel": "self"
                }
            ],
            "status": "CURRENT",
            "max_version": "2.42",
            "min_version": "2.1",
        },
   ]
}

虽然通常对于给定的服务只有一个 API，但有时能够提供给定 API 的多个版本也很有用。这方面的常见示例是，为了支持尚未升级到当前版本的客户端，仍然提供旧版本，或者在发布之前测试新 API 版本。为了区分相同服务的这些不同的 API，使用 status 值。可以为状态返回值如下

状态	含义
CURRENT	当前正在开发和改进的最新 API。除非您需要支持旧代码，否则请使用此 API。
SUPPORTED	API 的旧版本。不会向此版本添加新功能，但任何在代码中发现的错误都可能会修复。
DEPRECATED	此 API 将在可预见的未来被删除。您应该开始计划使用替代方案。
EXPERIMENTAL	此 API 正在开发中（“alpha”），您可以预期它会发生变化甚至被删除。

当请求的版本超出服务器的范围时，服务器返回状态码 406 Not Acceptable 以及响应体。

错误响应体符合错误指南 Errors，并包含以下 json-schema 中描述的两个附加属性

{
   "max_version": {
    "type": "string", "pattern": "^([1-9]\d*)\.([1-9]\d*|0)$"
   },
   "min_version": {
    "type": "string", "pattern": "^([1-9]\d*)\.([1-9]\d*|0)$"
   }
}

一个 HTTP 头部响应示例

HTTP/1.1 406 Not Acceptable
Openstack-API-Version: compute 5.3
Vary: OpenStack-API-Version

一个错误主体响应示例

 {
    "errors": [
        {
            "request_id": "2ee92f06-8ede-4fb4-8921-b507601fb59d",
            "code": "compute.microverion-unsupported",
            "status": 406,
            "title": "Requested microversion is unsupported",
            "detail": "Version 5.3 is not supported by the API. Minimum is 2.1 and maximum is 5.2.",
            "max_version": "5.2",
            "min_version": "2.1",
            "links": [
                {
                    "rel": "help",
                    "href": "https://developer.openstack.org/api-guide/compute/microversions.html"
                }
             ]
         }
     ]
}