在我职业生涯的早期，我花时间使用 实时框架 用 C 语言编写 Linux 内核模块和驱动程序。为了了解可供我使用的函数和库实用程序，我打印了官方文档。打印它花了一整天，我用一个三孔打孔器把它放进一个又大又厚的活页夹里。
当像这样的活页夹相关时，有一个非常丰富多彩的首字母缩略词，它曾经像现在的“pull request”这个词一样被随意使用。这句话的原始版本是“RTM”，代表“阅读手册”。无论是这个 版本还是彩色版本 ，信息和语气都很明确：沮丧的 API 开发人员告诉他们的用户在用愚蠢的问题打扰他们之前先阅读手册。
使用其他开发人员的代码有点像上大学课程。你会得到学习材料，并期望能相对快速地展示你的掌握程度。不言而喻，要取得成功需要付出很多努力。
我不想念那些日子。
我们不再阅读使用说明书；有时我们甚至得不到它们。当我们购买电子产品时，我们希望它们有一些小教程来引导我们了解它们的功能。当我们下载应用程序时，如果下一步该做什么不明显，我们会立即删除它们。而且，当涉及到 API 时，如果它们令人沮丧或困惑，我们就会寻找其他地方。
当我使用 RTAI 来编写我的驱动程序时，我无法选择使用什么框架，所以它的作者没有动力去特意让我的生活变得轻松。今天的用户更具选择性，要求易于使用、易于理解、信息的可访问性和愉快的整体体验。如今，如果您正在编写 API，那么您的竞争非常激烈，这意味着您需要不断回答“我为什么要使用 您的 API？”这个问题。这里有一些方法可以确保您满意地回答这个问题。
“当我们下载应用程序时，如果下一步该做什么不明显，我们会立即删除它们。而且，当涉及到 API 时，如果它们令人沮丧或困惑，我们就会寻找其他地方。”
让它变得简单
首先，让我们谈谈 API 本身。在过去的几年里，作为一名顾问，我最常参与的活动之一就是通常被描述为“工艺指导”的活动。客户通常对自动化测试等实践最感兴趣，但实际上归根结底，其核心是帮助团队编写干净、可维护的代码。简而言之，干净、可维护代码的关键是清晰。
命名要清楚，以便用户准确理解方法调用的预期内容。与 int Process(Invoice i) 相比，他们对 int ComputeSalesTaxFor(Invoice rawInvoice) 更满意。在编写方法、函数、端点等时设身处地为他们着想——如果您是新手， 您的 意图是否清楚？另一个重要的考虑因素是不要用选项来麻痹用户。当您向用户提供他们可能认为有用的每个选项时，您可能会觉得您是在负责，但这确实会导致混淆。用户体验让我们远离具有数十种“高级设置”的无限灵活的应用程序，这绝非偶然。当然，每 100 名用户中就有 1 名可能会因为无法根据假设的“公平税”方案和使用比特币计算销售税而感到恼火，但绝大多数用户只想要普通的旧 ComputeSalesTaxForInvoice(Invoice rawInvoice) 并且会感到恼火如果他们必须弄清楚如何处理一堆布尔标志或设置对象。
最后，一定要形成并提供一致、清晰的抽象，不要怪异。如果您的 API 允许您计算销售税并将其作为订单项添加到发票中，请不要强迫想要删除销售税的用户再次计算它，然后将其作为负数添加。如果您可以添加行项目，请在您的架构设计允许的情况下为要删除的项目提供支持。衡量您是否做得很好的一个好方法是抓住不熟悉您正在做的事情的开发人员，并根据您拥有的内容以及现有操作的行为方式询问他们期望看到的操作预计。
干净、简洁的 API 设计不会取代文档，但会显着减少文档部门对冗长和过度补偿的需求。一个简单明了的 API 会将其清晰度融入文档中，并最终融入开发人员围绕该 API 编写的代码中。从尽可能简单的设计开始，但不能更简单。
Dogfood 你自己的设计
在构建可以组合使用的多个 API 时，重要的是要考虑它们如何相互编排和转换。确保在每个 API 的良好设计原子性与它们如何在开发人员编写的最终代码中协同工作以实现其解决方案之间取得平衡。如果您有很多“小服务”，您的设计决策和工具需要反映出您预先考虑过这个问题。
取得这种平衡的最简单方法是测试您自己的设计。花 5 分钟时间编写一些集成代码，将您的 API 相互结合使用，以便从外部开发人员的角度充实最可能和最明显的尴尬组合以及任何明显的遗漏。在此过程中还要牢记一个目标，即 API 消费者体验最有可能推动或阻碍 API 的采用，就像将其写在便利贴上并将其放在 24/7 全天候可见的地方一样简单：“我的API 更适合他们而不是我。”
我们在 SmartBear 中使用的一个术语是“编排测试”，通过快速测试活动来实践上述 dogfooding API 设计原则。随着越来越多地采用微服务风格的方法，这种新的测试方式尤为重要，这种方法很可能会在您的 API 环境中造成严重的碎片化。 “小 API”越多，需要组合、测试、管理和监控的东西就越多。
可用并培养社区
假设您已经为您的用户在一个有用的产品上构建了一个漂亮干净的 API。这是非常重要的第一步，但您还没有完成。发布它并获得用户群可能是运营和销售方面的考虑，但您需要在围绕您的服务及其 API 创建社区方面发挥积极作用。
首先，这意味着可用性。确保当用户有疑问时，这些问题得到快速解答。如今，这需要的不仅仅是客户支持电子邮件地址。在社交媒体上可用并参与有关您的产品的对话至关重要。
不过，您不 只是 想回答问题并提供支持。总的来说，这个想法是围绕您的产品及其 API 建立一个社区。当有人在 Twitter 上发布问题并且答案来自与您的团队没有任何关联的另一个人时，您就会知道自己走在正确的轨道上。
提供实例！
这绝对是您可以采取的最关键的步骤，以确保您的 API 清晰且令用户满意。构建一个漂亮、干净的 API 将取悦用户，构建一个社区将有助于消除任何仍然存在的挫败感，但示例是最重要的。
说到示例， Trello 的 API 文档 非常棒，它毫不费力地在浏览器中提供了 API 的工作示例。
正如我之前所说，仔细研究手册页和大量使用文档的日子已经一去不复返了。用户现在通过实验来学习。他们下载您的库或点击您的端点并开始 使用 它。即使有一个漂亮、清晰的 API，他们也会有疑问并陷入困境。提供有关如何完成常见任务的示例，使他们从摸索中走出来，从成功开始，并通过调整在成功的基础上再接再厉。
对于 API 作者来说，没有什么比帮助用户在每一步都取得成功更重要的了。
提供 API 描述符
开发人员和最终用户并不是您的 API 的唯一消费者。如果您提供机器可读的 API 描述符（如用于 REST 的 Swagger 或用于 SOAP 的 WSDL），则第 3 方 框架、集成和工具通常更易于使用。但是 API 描述符到底是什么？
API 描述是 API 工作方式的可移植摘要。它们是有助于描述与其运行时实现分开的 Web 服务的行为、模式和其他细节的信息。
换句话说，您可以将 API 描述交给其他团队成员、合作伙伴或集成商，以帮助他们根据您的 API 进行构建……而无需提前建立您的实际 API。这可以是可通过 URL 访问的文件或文档，但无论哪种方式，其内容都符合一些众所周知的标准，用于描述 API 并定义您的服务可用于对外界做什么。
最好的部分是，因为您的 API 描述符是机器可读的，所以它不仅适合消费；它可用于 生成代码 、 模拟 、 文档 、 SDK ，并满足 API 设计生命周期中的一大堆其他 有价值的用例 。
即使您还没有 API 的描述符，也很有可能很容易生成一个描述符并立即开始受益。许多特定于框架的解决方案可帮助您扩充您已经编写的 API 代码以发出 API 描述文档，就像 WSDL 通常随 SOAP 样式的 Web 服务一起提供一样。这方面的示例是用于 Node.js 编写的 API 的“ swagger-node ”、用于 java API 的“ swagger4j ”和“ grpc-gateway ”，它包括为使用 Google 的 GRPC 框架的服务发出 Swagger 文档的能力。
我为什么要使用你们的 API？
显然，根据我上面的描述，我是一名程序员。我是一名需要解决问题的程序员，您的产品会为我解决。但我还不知道。
我要去谷歌，我会找到你的产品以及其他 20 个类似的解决方案。我要下载它并尝试一下，在遇到阻力时，我将退出并继续下一个选项。
你可以说我善变，你可以让我看说明书，但没关系。你失去了一笔生意。我对您的 API 的使用可确保薪水一直流向正确的地方。当您编写 API 并将其与您的用户群进行社交时，请始终在您的脑海中浮现一个假设的用户在问这样一个问题：“那么，我为什么要使用这个 API？”您的热情是您与其他竞争对手最大的区别；在你的 API 中尽可能使用它，它会向消费者表明你的 API 是值得使用的。