There and back again, a roadmap to API v2¶

https://blueprints.launchpad.net/sahara/+spec/v2-api-experimental-impl

随着 sahara 的 API 发展，已经引入了许多以路由和方法形式呈现的功能，这些功能可以以更一致和可预测的方式构建。此外，还有一些新的考虑因素和方法，只有通过更新 API 的主要版本才能解决。本文档是实现实验性 v2 API 的路线图，该 API 将构成最终稳定版本的基础。

注意

这是一个伞状规范，涵盖许多变更，将会后续发布规范来涵盖一些更复杂的细节。

问题描述¶

sahara 当前的 REST API 版本 1.1 包含几种方法和模式，这些方法和模式在 API 内部以及相对于 API 工作组不断发展的指南[1]中造成了不一致性。其中许多是由于设计的迭代性质造成的，有些是在稳定指南出现之前创建的。

当前 API 中不一致性的示例

方法端点名称不准确，例如“jobs”而不是“job-templates”。
JSON 资源中的特定技术参数，例如“oozie_job_id”而不是“engine_job_id”。
某些操作中 HTTP 方法的使用不当，例如使用 PUT 进行部分资源更新而不是 PATCH。

除了解决 API 中的不一致性之外，新版本还将提供一个机会来实现将改善 sahara API 消费体验的功能。

在新 API 中实现的功能示例

微版本支持，以帮助客户端应用程序发现功能。
创建任务端点和基础设施，以改善异步操作的使用。
在响应中嵌入 HREF，以改善资源位置发现。

这些只是可以在新的主要版本 API 实现中解决的一些问题示例。

提议的变更¶

为了解决创建新的主要版本 API 的问题，应该创建一个实验性的 /v2 端点。这个新的端点将被明确标记为实验性的，并且不会对子端点的内容强制执行稳定性合同。对 /v2 端点的更改将通过本文档中描述的功能以及将要创建的进一步规范来跟踪，以更好地描述较大更改的细节。

当对 /v2 端点的所有更改都已完成，使其与当前 API 的功能完全一致，并且 Python sahara 客户端已更新为使用这些新端点时，应评估 API 的实验状态，目标是将其标记为稳定并准备好供公众使用。

各个更改将分解为单个任务。这将允许 sahara 团队成员更轻松地研究和实施这些更改。这些工作将通过 sahara wiki 站点上的一个页面进行协调[2]。

初始 v2 提交¶

创建 /v2 端点的初始更改还应包括将 Identity 项目标识符移动到名为 OpenStack-Project-ID 的标头。在其他方面，当前在 /v1.1 API 中存在的端点将被携带到新的端点命名空间中。这将创建一个坚实的基础点，可以从中进行进一步的更改，因为新的 API 正在发展并朝着完成实验规范中描述的所有功能而努力。

将项目标识符从 URI 中删除将有助于创建更一致、可重用的客户端应用程序路由和嵌入的 HREF。此举还将有助于将 URI 作用域资源与单个项目标识符的概念解耦。

变更路线图¶

以下列表是所有应合并到实验性 API 中的更改的概述，然后才能考虑迁移到稳定版本。这些更改的优先级顺序不重要，可以并行进行。其中一些更改可以通过简单的错误来解决，这些错误应在其名称中标记为 [APIv2]。更复杂的更改应由标记有相同 [APIv2] 标记的规范预先定义。对于两种类型的更改，提交应包含 Partial-Implements: bp v2-api-experimental-impl 以帮助跟踪 API 转换过程。

变更概述

端点变更
- /images/{image_id}/tag 和 /images/{image_id}/untag 应更改为遵循关于标签的指南[3]。
- /jobs 应重命名为 /job-templates。
- /job-executions 应重命名为 /jobs。
- 通过 /jobs/{job_id}/execute 端点执行作业模板应更改为对新的 /jobs 端点执行 POST 操作。
- 通过 /job-executions/{job_execution_id}/cancel 端点取消作业执行应删除，以支持对新的 /jobs/{job_id} 端点进行 PATCH 请求以请求已取消状态。
- /job-binary-internals 应删除，以支持 /job-binaries，后者接受内部数据库引用的项目，可以在 /job-binaries 下创建一个端点来上传文件（如果需要）。
- /job-executions/{job_execution_id}/refresh-status 应删除，以支持对新的 /jobs/{job_id} 端点进行 GET 请求以获取正在运行的作业执行。
- 所有更新操作都应同步使用 PATCH 而不是 PUT 进行部分资源更新。
JSON 有效负载变更
- hadoop_version 应更改为 plugin_version。
- oozie_job_id 应更改为 engine_job_id。
- 所有返回的有效负载都应包装在其类型中，目前 API 都是如此，为了保持一致性，应保持不变。
- 应在包含对其他对象的引用中嵌入 HREF。
新功能
- Identity 项目标识符移动到标头。这将是版本 2 的初始版本，但值得注意的是一个重要的功能更改。
- 应添加微版本支持，这应在单独的规范中完全记录，但应基于 ironic[4] 和 nova[5] 项目所做的工作。虽然在实验阶段实现，但这些微版本在 API 被声明为稳定之前不会实现向后兼容性功能。一旦 API 移动到稳定阶段，微版本将仅为版本 2 实现向后兼容性，并且仅为稳定版本发布后添加的功能。
- 应通过添加对“主文档”的支持来改进版本发现，该文档将从版本 2 根 URL 返回。此文档将遵循 json-home[6] 草案规范。此外，将添加对使用先前的实现和 API 工作组指南作为指导来发现微版本的支持。
- 为集群创建一个操作端点，以提供对这些集群操作的单一入口点。该端点最初允许进行缩放等操作，但将在未来用于进一步改进。操作端点将是单独规范的主题，因为它将描述删除当前存在的几个基于动词的端点，以及创建用于同步和异步操作的新机制。

此列表并非旨在包含所有可能的未来更改，而是新 API 可以被声明为稳定之前必须进行的最少必要更改的窗口。

在 Python sahara 客户端更新为使用新功能之前，此 API 的稳定过渡不应发生。

替代方案¶

另一种选择是对当前版本 API 进行更改，但这不可取，因为它破坏了最终用户的 API 版本合同。

虽然可以更改当前版本 API，但无法安全地进行提议的更改而不破坏向后兼容性。由于提议的更改性质很大，因此不建议创建 API 的“1.2”版本。

数据模型影响¶

这些更改中的大多数不需要修改数据模型。两个主要的例外是 hadoop_version 和 oozie_job_id 的有效负载名称更改。由于数据模型将继续用于 v1.1 API，直到其被弃用，因此现在不建议重命名这些字段。当 v2 API 稳定后，并且 v1.1 API 已被弃用时，应重新访问这些字段并更改数据模型。

在 API 的实验阶段，这些转换将发生在处理请求和响应的代码中。在 API 过渡到生产模式后，应创建迁移以使数据模型与 API 表示对齐，并且仅在必要时为旧版本创建翻译。

REST API 影响¶

由于此规范正在解决 API 的高级更改，因此以下更改简要列出。对于需要更多操作才能完成的更改，应创建完整的详细信息。

创建 /v2 根端点
删除 URI 中的 {tenant_id}，替换为所有请求上的 OpenStack-Project-ID 标头。
删除对 /images/{image_id}/tag 的 POST
删除对 /images/{image_id}/untag 的 POST
创建对 /images/{image_id}/tags 的 GET/PUT/DELETE，这应遵循描述新的标记方法的规范。
创建对 /images/{image_id}/tags/{tag_id} 的 GET/PUT/DELETE，这也应包含在上述关于标记的规范中。
将对 /jobs 上的操作移动到 /job-templates
将对 /job-executions 上的操作移动到 /jobs
删除对 /jobs/{job_id}/execute 的 POST
创建对 /jobs 的 POST，这应在关于重构作业执行端点的规范中定义。
通过 /jobs 端点创建作业应从单个输入和输出字段过渡到使用较新的作业配置接口[7]。
删除对 /job-executions/{job_execution_id}/cancel 的 GET
创建对 /jobs/{job_id} 的 PATCH，这应在关于重构作业执行端点的规范中定义。
删除对 /job-executions/{job_execution_id}/refresh-status 的 GET
删除所有 /job-binary-internals 端点，其功能由 /job-binaries 提供，这可能需要创建单独的子端点来上传。
将对 /node-group-templates/{node_group_template_id} 的 PUT 重构为相同端点上的 PATCH。
将对 /cluster-templates/{cluster_template_id} 的 PUT 重构为相同端点上的 PATCH。
将对 /job-binaries/{job_binary_id} 的 PUT 重构为相同端点上的 PATCH。
将对 /data-sources/{data_source_id} 的 PUT 重构为相同端点上的 PATCH。

其他最终用户影响¶

在实验阶段，此更改不会对最终用户产生明显影响。一旦 API 稳定，用户需要切换 python-saharaclient 版本以及升级他们的 horizon 安装才能充分利用重命名的功能。

部署者影响¶

在实验阶段，此更改不会对部署者产生影响。

当 API 达到稳定阶段时，部署者将负责升级其安装，以确保 sahara 和 python-saharaclient 得到升级，并更改服务目录以表示基本端点。

开发者影响¶

由于此更改针对实验工作，开发人员应知道 v2 API 的细节将不断变化。没有稳定性的保证。

Sahara-image-elements impact¶

无

Sahara-dashboard / Horizon 影响¶

此更改不需要更改 horizon，因为许多正在更改的基元已经显示了正确的名称，例如“作业模板”。当此更改移动到稳定阶段时，应重新评估 horizon。

实现¶

负责人¶

主要负责人: Telles Nobrega
其他贡献者: mimccune (Michael McCune)

工作项¶

此规范的主要工作项是初始 v2 提交。

创建 v2 端点
创建处理标头中项目 ID 的代码
创建到当前端点的映射

依赖项¶

此更改不需要新的依赖项。

测试¶

将创建单元测试来测试新的端点。此外，应调查 gabbi[8] 测试框架作为 REST API 的功能测试平台。

为了改进安全测试，应调查 Syntribos[9] 和 RestFuzz[10] 等工具用于定向测试工作以及可能的门控测试。

这些调查如果发现足够的结果来证明其创建是合理的，将导致进一步的规范，因为它们将处理新的 sahara API 服务器测试模式。

当 v2 API 达到稳定状态，并且 python-saharaclient 已移植到使用新的 API 时，当前的功能测试应提供必要的框架以确保成功的端到端测试。

文档影响¶

在实验阶段，这项工作不会产生文档。当评估稳定时，将需要 api-ref[11] 站点的新版本的 WADL 文件，如果需要，该站点可能会更改其格式，在这种情况下，需要生成这些新的 API 文档。

此外，v2 API 应遵循 keystone 的模式[12]，将 API 参考文档以重构文本格式发布到 specs 仓库。这将使 API 更易于记录和更新，因为新的规范变更也可以提议到同一个仓库进行 API 变更。此外，WADL 格式非常冗长，并且在 OpenStack 文档社区中[13]该格式的未来存在疑问。为 sahara 的 API 创建准确的文档工作也应包括在 v2 API 趋于稳定时创建 Swagger[14] 输出的可能性，这应在接近该时间点时以更独立的规范来解决。