Watcher 的 API 微版本¶
https://blueprints.launchpad.net/watcher/+spec/api-microversioning
问题描述¶
随着 Watcher 的发展和新功能的获得，这些功能也体现在 API 变更中，因此支持 Watcher 的新版本而不破坏现有基础设施是必要的。
用例¶
作为 OpenStack 操作员，我希望从客户端 v1.1 向 Watcher API 服务器发送请求，版本为最新版本 1.2，并获得包含版本 1.1 资源的适当响应。
作为 OpenStack 操作员，我希望发送不指定 API 版本的资源请求，并获得包含默认版本资源的响应。
作为 OpenStack 操作员，我希望发送指定 API 版本为 1.2 的资源请求，并获得包含版本 1.2 资源的响应。
提议的变更¶
Watcher API 应该从客户端接收 API 版本，该版本代表它可以处理的资源列表及其 GET/POST/PATCH 属性。如果用户使用错误的 API 微版本发送请求，则应返回 HTTP 406 Not Acceptable。
由于 Watcher API 使用 Pecan + WSME 捆绑包，Watcher 微版本验证应在用于将资源适配到指定 API 版本的特殊方法集中完成。例如，如果补丁集在版本 1.2 中向资源添加了新属性，则版本 1.1 应该从响应中排除这些属性。我们将使用 Ironic 微版本规范 和实现的部分内容，因为它也使用了 Pecan + WSME 捆绑包。让我们看看 Watcher API 和 Watcher Client 之间通信的可能用例。我们将使用术语“旧 Watcher”来指代一个在微版本出现之前且不了解它们的 Watcher 版本。
不指定 API 微版本进行通信（旧 Watcher）¶
客户端建立与 Watcher 的连接，未指定 HTTP 标头 OpenStack-API-Version。
Watcher 未看到 OpenStack-API-Version HTTP 标头
Watcher 使用 REST API 的 v1.0 进行通信，所有与客户端的通信都使用该版本的接口。
旧客户端与新 Watcher API 之间的通信¶
客户端建立与 Watcher 的连接，指定 HTTP 标头 OpenStack-API-Version，版本为 1.0
Watcher 使用 REST API 的 v1.0 进行通信，所有与客户端的通信都使用该版本的接口。
新客户端与新 Watcher API 之间的通信¶
客户端建立与 Watcher 的连接，指定 HTTP 标头 OpenStack-API-Version，版本为 1.1。
Watcher 使用 REST API 的 v1.1 进行通信，所有与客户端的通信都使用该版本的接口。响应附带新的 HTTP 标头 OpenStack-API-Version。
新客户端与新 Watcher API 之间的通信（使用最新的微版本）¶
客户端建立与 Watcher 的连接，在 OpenStack-API-Version HTTP 标头中提供“latest”作为版本
Watcher 通过使用其支持的最新 API 版本进行响应，并在 OpenStack-API-Version 标头中包含此版本，以及 -Min- 和 -Max- 标头。
新客户端/新 API 之间的协商，不指定版本¶
Watcher 客户端支持版本 1.1 到 1.3，Watcher API 支持版本 1.1 到 1.2。
用户未向客户端指定版本
客户端建立与 Watcher 的连接，提供 1.3 作为微版本，因为这是客户端支持的最新微版本。
Watcher 响应 406 Not Acceptable，以及它可以支持的 -Min- 和 -Max- 标头（在本例中为 1.1 和 1.2）
客户端应该透明地进行，协商出客户端和服务器都将使用 v1.2。客户端还应该缓存此微版本，以便后续尝试无需重新协商微版本。
新客户端/新 API 之间的协商，指定版本¶
Watcher 客户端支持版本 1.1 到 1.3，Watcher API 支持版本 1.1 到 1.2。
用户指定客户端应使用的特定微版本（例如 1.3）
客户端建立与 Watcher 的连接，提供 1.3 作为微版本
Watcher 响应 406 Not Acceptable，以及它可以支持的 -Min- 和 -Max- 标头（在本例中为 1.1 和 1.2）
客户端将此报告给用户并退出
新客户端/新 API 之间的通信，使用不受支持的版本¶
客户端建立与 Watcher 的连接，提供 1.3 作为请求的微版本。
Watcher 响应 406 Not Acceptable，以及它可以支持的 -Min- 和 -Max- 标头（在本例中为 1.1 和 1.2）
客户端将此错误报告给用户
要使用微服务，客户端应在发送请求之前将 OpenStack-API-Version 标头添加到 HTTP 请求中。python-watcherclient 已经为其请求提供了 OpenStack-API-Version 标头。目前，版本为 1.0，我建议提供“latest”，这将始终请求 Watcher 的最新 API 版本。
什么变更需要新的微版本
查询参数的变更 例如：添加新参数、删除旧参数、更改参数类型。
资源的变更 例如：添加新资源、删除旧资源。
请求体的变更 例如：POST 请求体中新增字段 ‘audit_description’。
本规范还依赖于 微版本规范 作为所提议变更的基础。
备选方案¶
保持不变，当用户连同新的 OpenStack 发布一起更新 Watcher 时。这可能会导致无法为旧客户端提供服务的潜在问题。
数据模型影响¶
无
REST API 影响¶
Watcher API 应该接受 OpenStack-API-Version HTTP 标头。
安全影响¶
无
通知影响¶
无
其他最终用户影响¶
无
性能影响¶
无
其他部署者影响¶
开发人员影响¶
Watcher 的 REST API 的任何未来变更（无论是在请求中还是在任何响应中）都必须导致微版本更新，并在代码中进行适当的保护。
实现¶
负责人¶
- 主要负责人
alexchadin (aschadin@sbcloud.ru)
工作项¶
将 OpenStack-API-Version 标头推送到 API 层。
添加特殊的过滤方法。
实现 versions.py 模块，其中包含 API 变更的历史记录。
依赖项¶
无
测试¶
应添加适当的单元和功能测试。
文档影响¶
无
参考资料¶
https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html
历史¶
无
