API 团队中出现了一种日益增长的趋势，即更好地标准化他们的 API 设计流程。 对于许多人来说，标准化 API 设计的努力首先是一项内部练习，以确保参与设计、开发和测试 API 的每个人都达成共识。
设计指南可能会以 PDF 格式或在内部 Wiki 上发布，供所有人参考，并且会制定流程以确保团队遵循设计指南。 但是，许多公司更进一步，公开发布这些指南，作为与他们的 API 合作的开发人员以及任何其他想要从他们的经验中学习的人的参考。 Arnaud Lauret（更广为人知的名字是API 工匠）是 API Stylebook 的创建者，这是一个在线资源，致力于帮助 API 开发人员通过学习有效实施 API 设计标准化流程的组织来解决他们的API 设计挑战。Arnaud 审查了来自包括思科、谷歌、贝宝、微软和其他公司在内的各个行业的组织的设计指南，并将他的发现汇编到一个易于导航的资源中。
我最近有机会与 Arnaud 讨论 API Stylebook 的由来，并为那些开始建立自己的 API 设计指南的组织提供他的建议。正如 Arnaud 解释的那样，创建内部样式指南只是流程的开始。阅读下面的完整采访，了解接下来会发生什么，以及 Arnaud 从他在 API Stylebook 上的工作中吸取了哪些经验教训。
是什么启发您创建 API Stylebook 作为 API 设计人员的资源？
我创建 API Stylebook 是因为我很难找到解决基本 API 设计问题的方案，而且我认为可能不是只有我一个人这样。 当我开始设计 REST API 时，我的许多基本 API 设计问题都没有得到轻松解决。很难找到有关面临类似挑战的人们如何解决这些问题的信息。 有时我找不到任何问题的答案。 我也没有意识到在设计 API 时必须考虑的所有事项。
凭着经验，我形成了自己的答案，有时是好的，有时是糟糕的。我也意识到我错过了一些重要的方面。最让我困扰的不仅仅是不得不接受一些设计错误，而是这些错误在行业中太常见了，不应该有人再犯这些错误。这些问题已经被解决了很多次，不应该有人再浪费时间再次解决它们。 我想做一些事情来帮助人们不再犯同样的错误并浪费时间。这就是 API Stylebook 的开始。当时我意识到，越来越多的公司和公共组织通过公开其指南来分享他们设计 API 的方式。 所有这些指南都包含解决常见 API 设计问题的答案。
我开始收集它们，目的只是提供一个链接列表。但是，当我阅读它们时，我意识到仅仅提供一个链接列表可能并不能真正帮助设计人员快速找到解决方案。 由于它们彼此之间都非常不同—在它们的组织或使用的词汇方面—找到解决方案仍然可能是一个真正的负担。 因此，我决定列出这些指南涵盖的所有主题，并对它们进行规范化，以便快速直接地访问它们。因此，API Stylebook 诞生了。
您如何选择 API Stylebook 中涵盖的设计指南？在评估样式指南时，您会寻找哪些特定标准？
可能有很多关于 API 设计的博客文章，但我只想提供在现实场景中遇到过的资料。这就是为什么我只将公司真正使用的“官方 API 设计指南”添加到 API Stylebook 中。
您认为为什么越来越多的公司专注于标准化他们的 API 设计？
公司制定指南的最明显原因在于，一个组织中开发的 API 越多，就越需要它们彼此保持一致。 提供具有共同行为、模式和标准外观的 API 将大大简化想要使用它们的人员的工作，无论他们是否来自公司。 另一个原因可能是 API 设计的效率。有了指南，API 设计人员可以专注于真正重要的事情，而不是浪费时间无休止地讨论微小的细节或试图解决公司内部已经解决的设计问题。
我知道您已经多次谈论和撰写了关于 OpenAPI 的文章。您是否看到公司将 OpenAPI 等标准纳入他们的 API 设计指南中？
恕我直言，还不够 :-) 我只在 API Stylebook 上发现了两个（Haufe 和 Zalando）。但是 Zalando 绝对是如何使用 OpenAPI 的最佳示例。他们在设计阶段使用 OpenAPI 规范，将其存储在版本控制系统中，并使用名为 Zally 的自定义工具控制 API 设计。这太棒了！我们需要更多关于 OpenAPI 和设计控制的工具。Zalando 还提供了一些关于如何使用 OpenAPI 规范准确描述数据的提示。
我们经常看到的两个主题是治理和版本控制。您如何看待组织在其 API 样式指南中处理治理？
治理涵盖了从我们为什么制作 API 到它们应该如何设计以及如何处理它们的生命周期等许多主题。 API 设计指南可能涵盖了其中一些主题，但并非全部。除了版本控制之外，治理主题在 我分析的指南中没有得到很好的体现。 它们主要关注如何设计 API，而较少关注其他方面。但是，仍然有一些指南谈到弃用（Zalando 或 Atlassian）或 API 设计验证过程（Haufe）。我感觉到治理指南应该在一个或多个其他文档中描述，以避免混淆太多不同的关注点。
版本控制，这绝对是一个治理话题，并且与设计紧密相关，在指南中更常见。它通常通过如何调用API的特定版本来呈现。有各种策略，例如使用URL或内容协商。但是，如果你不知道所做的更改是否是破坏性的，那么了解如何区分API的两个版本毫无意义，而只有少数指南提供了这方面的信息。
谷歌提供了一些提示，但同样，Zalando 在这方面是最完整的。
对于那些正在开始实施API风格指南的组织，您是否还有其他建议或通过您的研究获得的经验教训？
不要妄想一旦写好指南，工作就完成了。指南必须不断发展，因为它们最初不会涵盖所有可能的问题。最重要的是，如果没有推广和控制所做的事情，没有人会阅读或遵守它们。如果你想了解更多关于API设计指南的缘由和方法，你应该来参加APIStrat，并参加我的会议API设计之王。
感谢阅读！ 正在寻找更多API资源？订阅Swagger新闻通讯。每月接收包含我们最佳API文章、培训、教程等的电子邮件。订阅