跳转到： 导航, 搜索

API 特别兴趣组

状态: 活跃

组织者：Chris Dent, Michael McCune, Ed Leafe

目的

通过使 OpenStack API 趋向于一致且务实的 RESTful 设计，来改善 API 使用者的开发体验。工作组 创建指南，所有 OpenStack 项目都应遵循这些指南进行新开发，并促进新 API 和现有 API 未来版本的融合。

通常，我们提出、讨论、审查和倡导所有 OpenStack 程序应遵循的 API 指南。工作组成员可以提出 API 指南。这些建议将由工作组讨论。当 API 模式的规范进行审查时（例如，一个 Nova 规范，用于其中一个 Nova API 模式），工作组成员应审查规范，并根据其遵循指南的程度提供反馈。工作组成员还负责在其所从事的 OpenStack 程序中倡导遵循 API 指南。

如何加入

加入我们，将您添加到我们的 成员 列表中，并关注以下任何我们的沟通渠道。如果您对 如何贡献 有任何疑问，请与我们联系。

沟通

对于电子邮件，我们将使用 openstack-dev 邮件列表，并在主题行前加上 [api]。理想情况下，任何在讨论其 API 的任何程序的 OpenStack 开发者也应开始使用 [api] 前缀，以便工作组成员可以收到相关讨论的警报。

对于 IRC，我们将使用 Freenode 上的 #openstack-sdks。

对于 OpenStack Summit，设计峰会会议。

对于会议，请参加 API 工作组会议。

有关跨项目联络人（联络人是 API WG 团队成员的第一联系人），请参阅 跨项目联络人

交付成果

1. 分析当前设计

这本质上是一种记录和可视化 API 当前设计的方式。它使我们能够汇集许多 API 设计示例，以便对其进行分析并作为讨论点。这些是应该效仿的良好设计示例，或应该避免的糟糕设计示例。它可以是 API 一致的地方或存在不一致的地方的示例。


2. 指南

商定的并接受的指南必须添加到 Git (GitHub 镜像) 中的版本控制文档中。目前对文档的提议更改可以在此 审查报告 中找到。


3. 审查

对影响任何 OpenStack 程序 API 的代码更改和规范的评论和 +1 或 -1 投票。

当代码更改影响 OpenStack API 并且存在关于这些更改是否符合指南的担忧时，项目成员可以随时邀请工作组成员进行审查。将组成员添加到审查中，发送带有 [api] 标签的电子邮件到 openstack-dev 列表，或将链接添加到 每周会议议程。

4. 公告邮件

当新的指南被接受时，必须将其宣布到 openstack-dev（不带 [api] 前缀，以提高可见性）。该邮件必须包含指向指南和历史记录（指向 wiki 和审查的链接）的链接。

从 Newton 周期开始，工作组正在试验每周新闻邮件，其中包含所有冻结公告，以及有关高优先级审查和工作组即将发布的新闻的信息。新闻邮件的模板可以在这里找到：API 工作组每周邮件模板。


5. OpenStack API WG 的错误

跟踪新指南或现有指南的重大更改的工作。


6. OpenStack 项目的 Bug

当新的指南被接受时，可以针对不遵循该指南的 API 提交 Bug。如果 Bug 强制进行向后不兼容的更改，则必须在 API 的下一个版本或微版本中修复。该 Bug 必须包含指向指南的链接。

如何贡献

贡献形式为上述交付成果。对于交付成果 2 和 3，您首先需要阅读 How_To_Contribute 中的如果您是开发人员部分。

1. 贡献于分析当前设计

  1. 从 当前设计 开始。
  2. 找到您要分析的 API 设计类别。如果不存在，请创建它。
  3. 编辑 wiki 页面并进行分析。


例如，您想分析所有执行分页的 API 的一致性。在分页类别中，创建一个表格，并并排列出所有 API 执行分页的方式。


2. 贡献于指南

  1. 遵循 开发工作流程
  2. 当您到达 项目设置 时，从 git clone git://git.openstack.org/openstack/api-wg.git 开始
  3. 继续进行您的更改工作流程
  4. 在创建全新的指南时，使用 示例指南模板


3. 贡献于审查

  1. 在 review.openstack.org 上找到影响任何 API 的审查（此 审查报告）。
  2. 在评论审查时
    1. 根据 指南，向审查中添加评论。
    2. 链接到指南，以便贡献者更好地理解您的理由。
    3. 请随时告知贡献者您是 API 工作组成员。
    4. 如果贡献者不同意您的审查评论，请邀请他们开始在 openstack-dev 邮件列表上使用 [api] 前缀进行讨论
  3. 对审查进行 +1 或 -1 投票


4. 贡献公告邮件

如果您提出了一项指南并且已被接受，请发送电子邮件到 openstack-dev 以宣布它（请参阅上述 #4）。


5. 跟踪新指南或现有指南的重大更改的工作

  1. 转到 OpenStack API WG 错误跟踪器。
  2. 搜索现有的 Bug
  3. 如有必要，创建新的 Bug


6. 贡献 OpenStack 项目的 Bug。

  1. 在 Launchpad 中找到该项目。
  2. 转到该项目的 Bug 跟踪器
  3. 报告 Bug，并确保单击“额外选项”并包含“api”标签


7. 参加每周 API 工作组会议 的讨论。

范围

包含范围

API 工作组专注于为向应用程序开发者/操作员公开功能的 HTTP API 创建指南。它不关心这些 API 的实现。

这些是关于未来和为现有 API 的当前版本提供输入（Bug）的指南。当向现有 API 的当前版本报告 Bug 时，其意图不是实际更改当前版本，而是改进 API 的下一个版本。

建议使用 API 定义格式（例如 Swagger、RAML、API Blueprint）来驱动服务的实现和客户端。

不包含范围

第三方 API（例如 EC2、S3、OCCI 等）不在范围内。

有相关的 应用程序生态系统工作组 (AE WG)。API 工作组 (API WG) 补充了最终用户工作组。API WG 专注于创建 API 指南，而 AE WG 专注于创建使用 API 的应用程序。这两组相遇的地方是 API，它构成了两者之间的契约。AE WG 的成员鼓励成为 API WG 的成员，反之亦然。

常见问题解答

问：我的 OpenStack 程序没有 API 模式或规范审查流程（例如 Nova 的）。我该怎么办？

A. 建议您的 OpenStack 程序采用 API 模式语言和规范审查流程。让 API 工作组拥有一些力量的最佳方法是审查 API 模式的规范。对审查发表评论并对遵循或不遵循 API 指南的 API 投 +1 或 -1 票，将使这个工作组有潜力在 OpenStack 中产生实际影响。

成员

请将自己添加到此列表中，如果您致力于改进 OpenStack API，请这样做。

从 "https://wiki.openstack.org/w/index.php?title=API_Special_Interest_Group&oldid=161960" 检索