微版本规范¶

本文档旨在提供关于如何在 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 标头的值是 [SERVICE_TYPE] [VERSION_STRING]。VERSION_STRING 必须匹配 “^([1-9]d*).([1-9]d*|0)$”。如果 VERSION_STRING 不匹配正则表达式模式，则返回 400 Bad Request，并带有符合错误指南 Errors 的错误响应体。
如果发送了 OpenStack-API-Version 标头，服务类型匹配，并且版本设置为特殊关键字 latest，则表现为指定了最大版本。

警告

latest 值主要用于集成测试，并且由于微版本不遵循 semver，因此不保证向后兼容性，因此不建议在客户端代码中依赖它。客户端应始终要求特定的微版本，但限制其可接受的版本范围在它理解的时间范围内。

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

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

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

OpenStack-API-Version: compute 2.22

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

注意

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

注意

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

当请求的版本超出服务器的范围时，服务器返回状态码 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"
                }
             ]
         }
     ]
}

微版本规范

微版本规范¶

版本控制¶

客户端交互¶

API 特别兴趣组 0.0.1.dev301

页面内容