API团队中，更好地标准化其API设计流程的趋势日益增长。对许多团队而言，标准化API设计的工作始于一项内部实践，旨在确保所有参与API设计、开发和测试的人员保持一致。
设计指南可能会以PDF形式在内部发布，或发布在内部Wiki上供所有人参考，并且会制定流程以确保团队遵循设计指南。但许多公司更进一步，将这些指南公开发布，作为与他们API合作的开发人员的参考，也供其他希望从他们的经验中学习的人士参考。Arnaud Lauret（更广为人知的是API匠人）是API Stylebook的创始人，这是一个在线资源，致力于通过学习那些有效实施API设计标准化流程的组织，帮助API开发人员解决他们的API设计挑战。Arnaud审查了来自思科、谷歌、PayPal、微软等各行各业组织的风格指南，并将其发现汇编成一个易于导航的资源。
我最近有机会与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设计指南可能会涵盖其中一些主题，但并非全部。在我分析的指南中，除了版本控制之外的治理主题并没有得到很好的体现。它们主要关注如何设计API，而较少涉及其他方面。但即便如此，一些指南仍然会谈到弃用（Zalando或Atlassian）或API设计验证过程（Haufe）。我感觉治理指南应该在一个或多个其他文档中描述，以避免混淆不同的关注点。
版本控制无疑是一个治理主题，并且与设计紧密相关，它在指南中出现的频率更高。它通常通过如何调用API的特定版本来呈现。有各种策略，如使用URL或内容协商。但是，如果您不知道所做的更改是否具有破坏性，那么了解如何区分两个API版本就毫无意义，只有少数指南提供了这方面的信息。
谷歌提供了一些提示，但就此主题而言，Zalando再次是最全面的。
对于那些正在开始实施API风格指南的组织，您在研究中还有其他建议或学到的经验吗？
不要以为一旦写好指南，工作就完成了。指南必须不断演进，因为它们最初不可能涵盖所有可能的问题。最重要的是，如果不推广它们并控制其执行，没有人会阅读或遵守它们。如果您想了解更多关于API设计指南的原因和方法，您应该来参加APIStrat并听我的会议“API设计之王”。
感谢您的阅读！正在寻找更多API资源？订阅Swagger新闻通讯。每月接收包含我们最佳API文章、培训、教程等的电子邮件。订阅