Blueprint-os-api-docs
- Launchpad Entry: OpenStack API 文档设计
- 创建者: Diane Fleming
- 贡献者: Anne Gentle, Sam Harwell
- 相关蓝图: Blueprint-restructure-documentation
- 相关 Bug: 1326515
- 相关文档: JSON/REST 检查清单
- 计划实施版本: Icehouse (部分); Juno (完整)
概述
此蓝图描述了 Icehouse 和 Juno 版本中改进 OpenStack 应用程序开发者和贡献者文档的计划。
除了为经验丰富的开发者提供文档外，此修订后的文档还将描述下一步，即终端用户如何使用仪表板和客户端命令与 OpenStack 云交互，以及如何通过直接使用 API 或通过 cURL 命令或开放 SDK 间接使用 API。
由于我们缺乏 API 指导信息，并且我们将 API 规范发布在 docs.openstack.org 页面上，OpenStack 用户误认为这些规范是官方 API 参考和指南（实际上并非如此）。此蓝图提出了将解决此问题的更改。
历史记录
自 2012 年中以来，OpenStack API 文档和开发团队已经制作了以下 API 文档
- 一系列 API 参考页面。最初是一个长页面，现在拆分为每个 OpenStack 项目一个页面。OpenStack 用户访问此参考信息以开发在 OpenStack 上运行的应用程序。这些页面反映了完全实现的 API。来源于 WADL 文件，并在此 仓库 中包含一些 XML 包装文本。
- 一系列 API 规范。这些规范记录了 API 开发者在开发 OpenStack API 时做出的设计决策。这些文档反映了正在进行中的 API，而不是完全实现的 API。这些文档由开发和文档团队维护。问题：由于我们缺乏 API 指导信息，并且我们将 API 规范发布在 docs.openstack.org 页面上，OpenStack 用户误认为这些规范是官方 API 参考和指南（实际上并非如此）。这些文档来源于 XML 和 WADL 文件，并位于以下仓库中
- * http://git.openstack.org/cgit/openstack/compute-api/ - Compute API v2 和扩展，Compute API v1.0
- * http://git.openstack.org/cgit/openstack/database-api/ - 云数据库 API v1.0
- * http://git.openstack.org/cgit/openstack/identity-api/ - Identity Service API v3, Identity Service API v2.0
- * http://git.openstack.org/cgit/openstack/image-api/ - Image Service API v2, Image Service API v1
- * http://git.openstack.org/cgit/openstack/netconn-api/ - Networking API v2.0 和扩展
- * http://git.openstack.org/cgit/openstack/object-api/ - Object Storage API v1
- * http://git.openstack.org/cgit/openstack/volume-api/ - Block Storage API v2.0
问题
此蓝图旨在解决这两个主要问题
- 我们缺乏 OpenStack 开发者指南。由于 API 总是对某人来说是新的，我们需要一本 API 参考页面的配套书籍，引导新用户了解 API 概念和用法。由于我们缺乏 API 指导信息，并且我们将 API 规范发布在 docs.openstack.org 页面上，终端用户误认为这些规范是官方 API 参考和指南（实际上并非如此）。
- 每个 API 项目当前都有两个版本的 WADL 文件：一个在 openstack/api-site 仓库中，一个在 openstack/project-api 仓库中。这些版本不同步。此外，有些 API 文档完全来源于 XML，即使存在 WADL（或 WADL）。因此，任何给定的 API 方法都有两个甚至三个版本的文档。拥有多个 API 版本和文档位置会使终端用户感到困惑，并为作者和开发者增加不必要的工作。
Anne Gentle 在 邮件 中记录了这些问题。
目标
在 Icehouse 和 Juno 版本中，我们计划如下解决上述 问题
目标 1 - 新的 API 指南
添加一个新的 API 指南，捕获并补充规范中现有的指导信息。好处：而不是在多个地方查找指导信息，终端用户可以转到单个文档，该文档引导他们了解 API 用法。
目标 2 - 改进的 API 参考页面
继续为每个已实现的 OpenStack API 提供一个 API 参考页面。将规范中的所有现有参考信息合并到 API 参考页面的 WADL 中。好处：通过在一个地方呈现已实现的 API 参考信息，终端用户可以清楚地了解文档的位置。
目标 3 - 为每个 API 参考页面生成 PDF 文件
添加每个 API 参考页面的 PDF 文件。每个 PDF 文件将从生成 API 参考页面的相同 WADL 文件生成。每个 API 参考页面将提供指向这些 PDF 的链接。好处：用户可以获得 API 参考页面信息的打印版本。
目标 4 - 将 API 规范移动到项目仓库并从文档主页移除
在移动现有 API 参考/规范中的内容到 API 参考页面的 WADL 中之后，移动 仓库 到相应的项目仓库。最后，移除 https://docs.openstack.org 页面上的 API 规范。文档团队将不再维护、构建或发布这些文档，因为这些文档描述的是正在进行中的 API。好处：减少 API 文档冗余。消除作者在 API 参考和指导文档方面的工作重复。将正在进行中的 API 的文档与已实现 API 的文档分开。让 OpenStack 开发者清楚地了解正在进行中的 API 的文档位置。
文档摘要
| 文档 | 更改 | 受众 | 详情 |
|---|---|---|---|
| OpenStack API 指南 | 新建 | 应用程序开发者 | Blueprint-os-api-docs#BLUEPRINT: API Guide (new) |
| OpenStack API 完整参考网页 | 修订 | 应用程序开发者 | Blueprint-os-api-docs#BLUEPRINT: API Complete Reference pages (revised) |
| OpenStack API 参考（规范） | 移动到项目仓库 | OpenStack 开发者 | Blueprint-os-api-docs#BLUEPRINT: API References (specs) (move to project repos) |
文档状态
| 文档 | 状态 |
|---|---|
| OpenStack API 指南 | 正在进行中。已完成对现有内容的分析，并开始在新书籍中创建章节。请参阅 Bug #1269854 |
| OpenStack API 完整参考网页 | 正在进行中。完全修改了 Object Storage API 参考页面，使用了现有规范中的内容。添加了许多缺失的材料和概念信息。添加了几个 API/方法的缺失方法和 WADL。添加了缺失的代码示例。 |
| OpenStack API 参考（规范） | 正在进行中，将仓库移动到 openstack-attic。 |
蓝图：API 指南（新）
目的
- 目标 1 - 新的 API 指南.
- 向开发者介绍 API 概念、常见任务以及与 OpenStack API 交互的方式。
- 为希望扩展 OpenStack API 或编写在 OpenStack 云上运行的应用程序的开发者提供指导。
- 来自 Anne Gentle：“我们需要 Google Developer Support Handbook 所说的 开发者指南：一种对话式的书面指南，用于使用 API。开发者指南是使用 API 的逐步指南 - 就像老师向学生解释 API 一样，但它以数字墨水写下来（而且不能反驳！）。其中一些学生可能不熟悉 API，一些学生可能完全不熟悉 Web 开发，一些学生可能是经验丰富的专业人士 - 该指南应该适用于所有人。”
- 来自 Sam Harwell：一个好的经验法则是 OpenStack API 指南（蓝图的第 4 项）不应包含无法从 API 完整参考中推导出的任何新信息。换句话说，您应该能够通过 API 完整参考中各个地方提供的特定信息来解释和证明 API 指南中呈现的每条信息。请注意，这并不降低 API 指南的重要性；只是因为信息在完整参考中可用，并不意味着用户在第一次阅读时能够理解 API 调用之间的详细关系。
资料来源
- Python 开发者文档
- 语言绑定文档
- Tempest 测试
- Block Storage Service API v2 参考
- Compute API v2 和扩展参考
- Identity Service API v2.0 参考
- Networking API v2.0 参考
- Image Service API v2 参考
- Image Service API v1 参考
- Object Storage API v1 参考
章节：入门
描述每个 API，并讨论用户可以使用哪些方式访问 API。
注意：该指南将为项目的 API 完整参考提供指导信息。项目的 API 完整参考将包括访问信息，即列出应在 Authenticate 返回的服务目录中使用的服务类型，以找到服务端点。它还将包括有关文本编码、内容类型等的信息。
章节：限制
讨论限制和计费。
从现有的 API 参考中提取材料。提供可用的示例。
注意：API 完整参考将包括有关 API 调用因人为限制（例如配额或速率限制）而失败的返回值的信息。基于此信息，可以编写客户端以在任何实际限制下都能良好地执行。API 指南中的其他信息可能包括特定供应商产品实施的限制的详细信息。
章节：概念
从现有的 API 参考中提取材料。例如，常规 API 信息（每个参考都有一个类似的部分 - 我们需要以一种智能的方式整合这些信息）。还讨论如何访问 API。
小节：认证
从现有的 API 参考中提取材料。提供可用的示例。
注意：在 API 完整参考中，Identity Service Authenticate 方法将描述认证过程。特定项目的 API 参考的摘要/概述部分然后可以提到所有调用都需要包含带有从 Identity 项目的 API 完整参考中获得的 Authenticate 方法的值的 X-Auth-Token 标头。API 指南中的其他信息，即 API 完整参考中未直接表达的信息，将是关于过期令牌的客户端最佳实践的建议。
小节：请求/响应类型
从现有的 API 参考中提取材料。提供可用的示例。
小节：链接和引用
从现有的 API 参考中提取材料。提供可用的示例。
小节：分页集合
从现有的 API 参考中提取材料。提供可用的示例。
小节：使用 Changes-Since 参数进行高效轮询
从现有的 API 参考中提取材料。提供可用的示例。
小节：版本
从现有的 API 参考中提取材料。提供可用的示例。
小节：扩展
从现有的 API 参考中提取材料。提供可用的示例。
小节：错误
从现有的 API 参考中提取材料。提供可用的示例。
注意：API 调用所有可用错误信息应出现在该调用的 API 完整参考中。这在 JSON/REST 检查清单的 Responses 部分中更详细地介绍。
步骤 1：将以下指南中的信息编译成一个。
章节：使用 API
教程、示例，穿插着特定的 API 概念（例如存储类型、镜像、实例、实例救援等）。
通用词汇表
蓝图：API 完整参考页面（修订）
目的
- 目标 2 - 改进的 API 参考页面
- 目标 3 - 为每个 API 参考页面生成 PDF 文件
- 为开发者提供可搜索和全面的网页，其中列出了 API 方法和参数，并为每个方法提供示例。
- 为每个项目提供一个参考页面：Compute、Image Service、Identity Service、Object Storage、Networking、Orchestration 和 Block Storage Service（已实现）。来自 Sam Harwell：我的主要担忧是生成的完整参考页面的大小。如果将产品的整个 API 呈现在一个页面上，那么它对移动设备或作为社区答案的一部分将用户链接到特定信息都不友好。除了 URI 信息和示例之外，JSON/REST 检查清单 中的所有信息对于持久的 API 参考价值至关重要。
- 在删除 API 参考之前，从它们中提取参考材料到 WADL 文件。
- 从 WADL 文件（已实现，但 WADL 文件将使用更多信息进行更新）中提取 API 参考页面的参考信息。
- 审查并改进现有内容，使其包含完整的描述、请求和响应参数以及经过测试的代码示例。
- 使用 Sam Harwell 的 JSON/REST 检查清单 来改进文档。在单独的努力中，Sam Harwell 和 David Cramer 计划确定 JSON/REST 检查清单中的每个信息片段如何适合 WADL 文件。然后，David 计划增强 clouddocs-mvn-plugin，以便它验证 WADL 文件的完整性并从 WADL 文件中提取更多信息以进行显示。
- 注意： API 指南将为项目的 API 完整参考提供指导信息。项目的 API 完整参考将包含访问信息，形式为列出应在 Authenticate 返回的服务目录中使用的服务类型，以定位服务端点。它还将包含有关文本编码、内容类型等信息。
源材料
- API 参考 - 源自 WADL 文件
- API 参考/s - 将现有 API 参考/s 中的材料拉取到 WADL 文件中，以便所有内容都从 WADL 文件中单源生成。
蓝图：API 参考 (规范) (移动到项目规范仓库)
策略
从 docs.openstack.org 站点移除这些书籍，并将源文件从 docs 项目-api 仓库移动到项目规范仓库（见下文）
- Block Storage Service API v2 参考
- 块存储服务 API v1 参考 (在仓库中，但不在 docs.openstack.org 上)
- Compute API v2 和扩展参考
- 计算 API v1.0 参考 (在仓库中，但不在 docs.openstack.org 上)
- 云数据库开发者指南 v1.0 (在仓库中，但不在 docs.openstack.org 上)
- 身份服务 API v3 参考 (在仓库中，但不在 docs.openstack.org 上)
- Identity Service API v2.0 参考
- Networking API v2.0 参考
- 网络 API v1.0 参考 (在仓库中，但不在 docs.openstack.org 上)
- Image Service API v2 参考
- Image Service API v1 参考
- Object Storage API v1 参考
- 使用 Shell 和 Python 编程计算 API，第 1 版 (在仓库中，但不在 docs.openstack.org 上)
将这些书籍中的材料移动到源自 API 完整参考网页的 WADL 文件中。
将实际内容移动到项目仓库
注意
当现有源文件移动到项目仓库后，文档团队将不再负责这些文档的维护、构建和发布。
文档团队将确保应用程序开发者在 API 参考页面和（单个）API 指南上拥有可用的 API 信息。
此外，指向这些书籍的任何现有书签都将重定向到 http://api.openstack.org/api-ref.html。
