应用程序开发者指南 - 又名 API 指南¶

问题描述¶

多年来，我们一直在发布 API 参考文档。然而，应用程序开发者还需要概念性、操作指南和最佳实践信息。

目标¶

为了更好地服务 developer.openstack.org 的受众，我们计划

• 更新着陆页和网页，使 developer.openstack.org 更加易用
• 根据开发者选择的语言，提供信息
• 通过每个服务仓库本身获取有关服务能力和 REST API 的信息
• 确保“OpenStack 上的第一个应用程序”是一个完整且易于使用的入门指南
• 自动化 API 参考信息的生成
• 创建优秀、有用、准确、充分的应用程序开发者指南
• 遵循 API 工作组的文档指南进行标准化
• 围绕开发者任务和工作流程而非服务来组织指南

提议的变更¶

考虑到这些一般性指导原则，让我们从多个来源构建一个新的指南，其大纲如下

• OpenStack REST API 简介

• 在 OpenStack 上构建你的第一个应用程序

• 发现 OpenStack 服务、工作流程和资源

  • 以用户身份进行身份验证
  • 检查服务目录
  • 确定你需要哪些服务和资源
    • 镜像
      • 管理镜像
    • 计算实例 (虚拟机)
      • 了解风味和镜像
      • 启动实例
      • 向实例提供用户数据
      • 管理访问和安全
        • 使用密钥对
        • 使用安全组
      • 迁移实例
    • 网络
      • 创建网络、端口、路由器、子网
      • 在服务器之间进行负载均衡
    • 块存储
      • 使用块存储附加卷
      • 将卷从服务器传输到服务器
    • 对象存储

• 在 OpenStack 上部署应用程序

• 在 OpenStack 上排查应用程序问题

• 库和软件开发工具包

  • Python
  • Go
  • .Net
  • Java
  • nodejs
  • Ruby
  • PHP

• 基于 Swagger 的完整 API 参考，每种方法都应包含以下信息

  • 方法 (GET/PUT/POST/PATCH/HEAD/DELETE)
  • 资源 (由 URL 标识)
  • 请求参数、类型和描述，包括是否为可选参数
  • 请求头，包括 media-type、content-type、accept 等
  • 响应头 (对于某些 API)
  • 响应，包括类型和描述
  • 示例请求头和正文
  • 示例响应头和正文
  • 状态码：成功和错误响应码
  • 资源模型：可以消耗和生成的数据类型

  这些服务是本团队本次发布的工作范围

  • Identity
  • 计算
  • 镜像
  • 网络
  • 块存储
  • 对象存储

• OpenStack 应用程序的最佳实践

每个部分将如何获取信息？来自

• api-site 仓库中的 API 快速入门
• api-site 仓库中的第一个 OpenStack 应用程序
• 刷新 api-site 仓库中的着陆页
• 每个 OpenStack 服务仓库中的 api-guide 文件夹，例如 nova
• 包含迁移的 Swagger/RST 源文件的 api-ref 信息

消费者将如何找到并阅读这些文章？来自

• https://developer.openstack.org
• https://developer.openstack.org/firstapp-libcloud/
• https://developer.openstack.org/api-guide/quick-start/
• https://developer.openstack.org/api-guide/compute/
• https://developer.openstack.org/sdks/ (需要一个着陆页，目前我们使用 developer.openstack.org/#sdks，着陆页上的一个锚点)
• https://developer.openstack.org/sdks/python/openstacksdk/

等等，随着我们用内容填充上述大纲。

那些不在本大纲中的项目怎么办？

本大纲建议后续项目遵循的模式。本大纲为应用程序开发者文档创建了一个框架。我们期望 trove、sahara、ironic 和其他项目遵循此模式，以最好地服务于他们的用户。

实现¶

随着 WADL 到 Swagger/RST 迁移概念验证和 nova 仓库到 developer.openstack.org 站点发布概念验证的完成，以下工作项目部分描述了剩余的实施任务。

依赖项¶

• fairy-slipper 的概念验证完成
• 将 fairy-slipper 移动到 OpenStack Gerrit：https://review.openstack.org/#/c/245352/

测试¶

这些交付物使用经过测试的 openstackdocstheme Sphinx 主题。目前预计不需要额外的测试资源。

参考资料¶

• https://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
• https://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html
• https://etherpad.openstack.org/p/nova-v2.1-api-doc
• https://etherpad.openstack.org/p/Mitaka-Docs-API
• http://superuser.openstack.org/articles/openstack-application-developers-share-insights
• https://developer.openstack.org
• https://developer.openstack.org/firstapp-libcloud/
• https://developer.openstack.org/api-guide/quick-start/
• https://developer.openstack.org/api-guide/compute/