跳转到： 导航, 搜索

API SIG

正在进行的工作

链接需要更新

状态: 活跃

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

目的

通过统一 OpenStack API 为一致且务实的 RESTful 设计，从而改善 API 用户开发体验。SIG（Special Interest Group，特别兴趣小组）创建指南，所有 OpenStack 项目在新开发中都应遵循这些指南，并促进新 API 和现有 API 未来版本的统一。

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

如何加入

要加入，请将自己添加为我们的 成员，并关注以下任何一种沟通渠道。如果您对 如何贡献有任何疑问，请与我们联系。

沟通

对于电子邮件，我们将使用 openstack-discuss 邮件列表，用于内部讨论和与开发人员关于其 API 的讨论。请务必在主题行前加上 [api]。理想情况下，任何 OpenStack 程序中的任何开发人员在讨论其 API 时也应开始使用 [api] 前缀，以便小组成员可以收到相关讨论的警报。

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

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

对于会议，请参阅 API SIG 会议。

对于跨项目联络人（联络人是 API-SIG 团队成员的第一联系人），请参阅 跨项目联络人

交付成果

1. 分析当前设计

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


2. 指南

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


3. 审查

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

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

4. 公告邮件

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

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


5. OpenStack API-SIG 的错误

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


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-sig.git 开始
  3. 继续进行您的更改工作流程
  4. 在创建全新的指南时，请使用 示例指南模板


3. 贡献于审查

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


4. 贡献公告邮件

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


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

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


6. 贡献 OpenStack 项目的 Bug。

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


7. 参与每周 API-SIG 会议的讨论。

范围

包含范围

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

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

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

不包含范围

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

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

常见问题解答

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

A. 建议您的 OpenStack 程序采用 API 模式语言和规范审查流程。让 API-SIG 具有一定影响力的最佳方法是审查 API 模式的规范。对审查发表评论并对遵循或不遵循 API 指南的 API 投 +1 或 -1 票，将使该小组有可能对 OpenStack 产生实际影响。

成员

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

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