为什么开发者不使用你的API

最近和几个技术朋友聊天，他们都在抱怨一件事：市面上太多API的文档写得一塌糊涂，导致他们宁愿自己造轮子也不愿意接入。作为Baklib的研究员，我深知开发文档建设对于开发者体验的重要性——一份清晰、易用的文档，往往是开发者决定是否采用你产品的第一道门槛。很多团队花了大把精力打磨API本身，却忽略了文档这个“面子工程”，结果就是开发者来了又走，留存率惨淡。Baklib在帮助企业搭建开发文档时，特别强调从开发者视角出发，提供快速入门、代码示例、沙箱测试等环节，让文档真正成为连接产品与开发者的桥梁。

你创建了API，并期望开发者使用它们，但一段时间后，你发现事情有些不对劲——开发者并没有像你期望的那样频繁查阅你的开发文档。这是为什么呢？原因可能有很多，而你可以采取相应的措施来改善局面。在本文中，我们将探讨一些可能让开发者远离你API的常见错误，当然，也会告诉你如何修复它们。

如果开发者有充足的时间，他们很乐意仔细研究你API的每一个细节。但现实是，开发者需要在编写代码、参加会议、处理Bug以及应对其他日常任务之余，还要熟悉新的API，这往往会让他们感到不堪重负。这就是为什么你应该提供一个简单的入口，让入门变得更轻松。

是的，API很复杂，开发者需要掌握它们，但如果你希望开发者达到那个水平，他们需要一个不会让他们一开始就感到畏惧的起点。正如经验丰富的API专家Jarkko Moilanen所说，你应该尽快为开发者提供积极的API使用体验。那么，如何提供一个快速便捷的入门途径呢？一种方式是通过API本身——与其强迫开发者通读所有内容，不如创建一个快速入门指南。请记住，目的是让开发者快速上手，所以快速入门指南应该简洁明了，演示API的基本工作原理。例如，看看Mailgun通过API发送邮件的快速入门指南，它非常精简：提供一个开发者应运行的命令，并解释执行该命令后会发生什么。这不是对Mailgun API工作方式的详尽说明，但它给了开发者基本的理解和良好的起点。

另一个重要因素是登录流程的便捷性。如果过程太复杂，一开始就会劝退一部分开发者。一个可行的解决方案是允许开发者使用第三方服务（如GitHub）登录。大多数开发者已经拥有GitHub账号，添加一个“通过GitHub注册”的按钮可以省去他们填写信息的时间。简而言之，如果开发者认为开始使用你的API需要太多时间，他们很可能会放弃。因此，不要低估降低入门门槛的重要性。

开发文档是开发者决定是否使用你API的关键因素。文档应该为开发者提供关于API的所有必要信息，如果质量不够好，开发者就缺乏可靠的知识资源来依赖。然而，第一步是提供开发文档本身。根据Postman发布的《2022年API现状报告》，55%的受访者指出，缺乏文档是使用API的首要障碍。因此，通过创建开发文档，你可以消除开发者使用API的最大障碍。但是，仅仅有文档可能还不够，它必须是高质量的文档，能够激励开发者使用API并提供所有必要信息。

那么，高质量的文档包含什么？技术分析师兼记者Jennifer Riggins指出，有价值的开发文档应包含以下内容：

代码示例对开发者尤其有用，通过展示实际代码，可以降低抽象程度，使文档更容易理解。例如，Plaid在其开发文档中，将代码与引用它的文本并排放置。此外，不建议将开发文档分散到太多页面。如果开发者需要点击数十个链接、搜索多个页面才能找到信息，他们会感到很不满，甚至可能完全放弃使用API。Pixeltech的James Yu给出了建议：“不要把文档分散到百万个不同的页面上。把相关主题放在同一页面上，彼此靠近。”例如，Backbone.js将所有文档放在同一页面上，并通过左侧导航菜单帮助开发者快速定位信息。开发文档中有很多元素可能会影响其质量，但如果执行得当，同样可以成为提供良好体验的契机，激励开发者使用你的API。

如果你想鼓励某人试用你的产品，提供一个无压力的试用方式是个好主意。同样的原则也适用于开发者和API。开发者不愿使用你API的原因之一，可能仅仅是因为他们对新事物犹豫不决。由于不熟悉你的API，开发者可能不确定它是否满足自己的需求，甚至是否值得花时间。但给他们一个机会来测试API、实验并了解其工作原理，可以让他们更容易决定使用你的API。你可以通过提供API沙箱来给予他们这个机会。

什么是API沙箱？技术作家Thomas Bush的定义是：“一个虚拟环境，开发者可以在其中以模拟方式测试API调用。”API沙箱的目的是让开发者在不承担任何义务的情况下体验真实的API使用。换句话说，他们可以在受控环境中测试功能和使用API，而无需在准备好之前注册、订阅或付费。这也有利于你和你的公司，因为你可以展示API并开始引导开发者。如果开发者决定在沙箱之外使用你的API，他们已经知道如何使用以及能实现什么。例如，Fiserv为开发者提供了一个API沙箱，开发者可以选择功能和端点，如“Payments”功能和“Charges”端点，然后调整参数、输入值，点击“运行”即可看到响应。这样的沙箱能帮助开发者轻松上手，让他们毫无顾虑地尝试，最终成为真正的用户。

迟早，开发者在使用你的API时会遇到问题。这是预料之中的，因为任何像软件这样复杂且动态的事物都不可能始终完美运行。然而，出现故障本身可能不是开发者放弃你API的唯一原因，更可能是因为你没有提供任何解决问题的资源。故障排除资源能在事情不按计划进行时提供快速解决方案和支持，这对开发者来说是无价的。他们需要知道在哪里可以找到帮助，并能合理快速地获得帮助。否则，他们可能会寻找其他拥有更好支持资源的API。

故障排除资源需要简单高效。例如，Cisco有一个API故障排除清单，包含十个问题，帮助开发者找到问题的根源。它不是高科技解决方案，也不需要是。它是开发者文档的一部分，以直接高效的方式帮助开发者解决常见问题。另一种提供故障排除资源的好方法是建立一个社区，让开发者可以互相寻求帮助，也可以从你和你的团队那里获得帮助。例如，Bullhorn有一个面向开发者的支持论坛，拥有超过一千个关于API的话题。不是所有话题都是关于故障排除，但其中很多涉及各种问题。通过提供社区支持，你让开发者更愿意持续使用你的API。

---

Baklib 致力于提升数字化员工体验。我们提供维基 Wiki + 内联网 + 智能搜索三合一的数字内容体验云平台，让知识查找和沉淀变得毫不费力。 适用于IT、HR、内部协作部门。