API设计指南：来自API手册的经验教训

API 团队越来越倾向于更好地标准化其 API 设计流程。对于许多团队来说，标准化 API 设计的努力始于一项内部练习，以确保参与设计、开发和测试 API 的每个人都在同一步调上。

设计指南可能会在内部以 PDF 格式或在内部 Wiki 上发布供所有人参考，并且会制定流程确保团队遵循设计指南。但许多公司更进一步，将这些指南公开发布，供使用其 API 的开发人员以及任何想要学习其经验的人参考。Arnaud Lauret（更为人熟知的名字是API Handyman ）是API Stylebook的创建者，这是一个在线资源，致力于帮助 API 开发人员通过向已有效实施标准化 API 设计流程的组织学习来解决他们的API 设计难题。Arnaud 审查了来自思科、谷歌、Paypal、微软等各行各业的组织的风格指南，并将他的研究结果汇编成一个易于浏览的资源。

最近，我有机会与 Arnaud 谈论了 API 手册的诞生过程，并听取了他对那些开始制定自己的 API 设计指南的组织的建议。正如 Arnaud 所解释的那样，创建内部指南只是这个过程的开始。请阅读下面的完整采访，了解接下来的内容，以及 Arnaud 从 API 手册的工作中学到的经验教训。

是什么启发您创建 API 手册作为 API 设计人员的资源？

我之所以创建 API 手册，是因为我很难找到解决基本 API 设计问题的方法，而且我认为我可能不是唯一一个。当我开始设计 REST API 时，我的许多基本 API 设计问题都不容易解决。很难找到有关面临类似挑战的人如何解决这些问题的信息。有时我找不到任何问题的答案。而且我不知道在设计 API 时必须考虑的所有事项。

凭借经验，我制定了答案，这些答案有时很好，有时很糟糕。我还意识到我错过了一些重要的方面。除了不得不忍受一些设计错误之外，最让我困扰的是，这些错误在行业中如此常见，以至于没有人应该犯这些错误。这些问题已经被解决了很多次，没有人应该再浪费时间去解决它们。我想做点什么来帮助人们避免犯同样的错误和浪费时间。这就是 API 手册的起源。我当时意识到，越来越多的公司和公共组织正在通过公开他们的指南来分享他们设计 API 的方式。所有这些指南都包含常见 API 设计问题的答案。

我开始收集这些指南，目的只是提供一个链接列表。但在阅读这些指南时，我意识到仅仅提供一个链接列表可能并不能真正帮助设计师快速找到解决方案。由于这些指南在组织或使用的词汇方面都大不相同，因此找到解决方案仍然可能是一个真正的负担。因此，我决定列出这些指南涵盖的所有主题，并对其进行规范化，以便快速直接地访问它们。就这样，API 手册诞生了。

您如何选择 API 手册中涵盖的设计指南？评估指南时，您是否会遵循某些标准？

可能有成千上万的博客文章谈论 API 设计，但我只想提供在现实世界中遇到的材料。这就是为什么我只将公司真正使用的“官方 API 设计指南”添加到 API 手册中。

您认为为什么越来越多的公司致力于标准化其 API 设计？

公司制定指南的最明显原因是，组织中开发的 API 越多，就越需要它们彼此保持一致。提供具有共同行为、模式和标准外观的 API 将大大简化想要使用这些 API 的人的工作，无论他们是否来自公司。另一个原因也可能是 API 设计的效率。有了指南，API 设计师就可以专注于真正重要的事情，而不是浪费时间无休止地讨论微小的细节或尝试解决公司内部已经解决的设计问题。

我知道您已经就 OpenAPI 发表过很多演讲和文章。您是否看到公司将 OpenAPI 之类的标准纳入其 API 设计指南中？

我认为还不够 🙂 我在 API 手册上只发现了两个（Haufe 和 Zalando）。但Zalando绝对是如何使用 OpenAPI 的最佳示例。他们在设计阶段使用 OpenAPI 规范，将其存储在版本控制系统中，并使用名为Zally 的自定义工具控制 API 设计。这太棒了！我们需要更多围绕 OpenAPI 和设计控制的工具。Zalando 还提供了一些关于如何使用 OpenAPI 规范准确描述数据的提示。

我们看到经常出现的两个主题是治理和版本控制。您认为组织如何在其 API 指南中处理治理问题。

治理涵盖了很多主题，从我们为什么要制作 API 到应该如何设计它们以及如何处理它们的生命周期。API 设计指南可能涵盖其中一些主题，但不是全部。除了版本控制之外，治理主题在我分析过的指南中并没有得到很好的体现。它们主要关注如何设计 API，而较少关注其他内容。但是，仍然有一些指南谈到了弃用（Zalando或Atlassian）或 API 设计验证过程（Haufe）。我认为治理指南应该在一个或多个其他文档中描述，以避免混淆太多不同的关注点。

版本控制绝对是一个治理主题，与设计紧密相关，在指南中更常见。它通常通过如何调用特定版本的 API 来呈现。有各种策略，例如使用 URL 或内容协商。但是，如果您不知道所做的更改是否具有破坏性，那么知道如何区分 API 的两个版本就毫无意义，而且只有少数指南提供了有关此方面的信息。

Google提供了一些提示，但Zalando在这方面的回答最全面