Your API Docs Are Why Nobody Uses Your API \u2014 TXT1.ai

没有人谈论的230万美元文档问题

我是陈莎莎，过去11年担任三家不同API优先公司的开发者关系主管。在2019年，我目睹了一家B轮初创公司耗尽230万美元工程资源，构建他们所称的“物流API的Stripe”。这个产品确实具有创新性——实时包裹追踪，亚秒延迟，预测送达窗口和无缝承运人集成。发布六个月后，他们只有47个注册用户。一年后，仅有3个付费客户。

问题不在于API。我自己测试过——它快速、可靠，并解决了真实的痛点。然而，文档却是一堂如何排斥开发者的精湛课。身份验证示例不起作用。假设你已经知道API作用的端点描述。单一语言的代码示例（自然是Java，因为这是后端团队使用的语言）。没有交互式游乐场。没有真实世界的用例。只有自动生成的参考文档，读起来就像机器人写的电话簿。

那家公司最终进行了转型。但在我心中挥之不去的是：这并不是个例。在我的职业生涯中，我审查过89种不同的API文档——从微小的初创公司到财富500强企业。我可以用一只手数出那些真正帮助开发者成功的文档数量。其余的？正是导致你的API激活率只有3%的原因。正是导致开发者注册，花费20分钟感到沮丧却再也不回来的原因。

这不是关于“写得好”。而是要理解，文档是你产品的第一印象、你的销售团队和你的支持系统的结合。而现在，它可能正在让你失去的客户比你的定价还要多。

预测API成功的五分钟测试

我在评估每个API时都有一个简单的测试。我称之为“五分钟首次调用”测试。其工作原理是：我创建一个帐户，导航到文档，并尝试在五分钟内成功进行第一次API调用。没有产品的先前知识。没有销售或支持的帮助。只有我、文档和一个计时器。

"文档不是锦上添花——它是1000万美元年收入API业务与200万美元损失之间的区别。开发者不是读心术；他们读的是文档。"

结果令人震惊。在过去三年中我测试的89个API中，只有7个通过了。这意味着只有8%的成功率。首次成功调用的平均时间是多少？34分钟。对于一名自2013年以来一直在处理API的人来说，这个时间太长了。对于一名初级开发者或新入门的人员来说，可能需要两倍或三倍的时间。

有趣的是，文档最佳的公司并不一定是预算最大的公司。Stripe的文档确实很棒，但Plaid的文档也同样出色。Twilio也是，Resend也是，这是一家成立不到两年的公司。共同的线索不是资源，而是哲学。这些公司理解文档不是发布后待办事项，而是产品本身。

当我深入探讨大多数API为何未能通过此测试时，三种模式持续显现。首先，缺乏明确的“入门”路径。开发者落在一个参考页面上，必须反向工程基本知识。其次，身份验证被当作事后思考——模糊的说明、缺失的凭据、不明确的作用域。第三，更致命的是：缺乏即时反馈循环。开发者在设置中投资了30分钟以上才能判断自己是否正确。

通过我测试的公司采取了截然不同的方法。他们假设你一无所知。在前60秒内提供一个可用示例。在你甚至发出请求之前就展示响应。他们让成功感觉是必然的，而不是像解谜游戏。

为什么自动生成的文档正在扼杀你的采用率

我直截了当地说：如果你的文档主要是从代码注释自动生成的，那么你正在积极破坏你的API成功。我知道这很有争议。我知道你的工程团队喜欢Swagger/OpenAPI。我知道它节省时间。但从我对23种不同API产品的开发者行为跟踪中学到的经验是：自动生成的文档的放弃率比人工编写的文档高67%。

问题不是自动生成的文档不准确——它们通常在技术上是正确的。问题在于它们针对的观众错误。它们是为构建API的工程师编写的，而不是为试图使用它的开发者。它们描述代码的功能，而不是解决的问题。它们列出了参数，却没有解释你为什么要使用它们或不使用它们时会发生什么。

我曾为一家拥有美丽OpenAPI规范的金融科技公司提供咨询。每个端点都有文档。每个参数都有类型和描述。但是当我问开发者API实际上做了什么时，他们却无法告诉我。文档解释POST /transactions端点“创建一个带有指定参数的事务对象。”这在技术上是正确的。但完全无用。

开发者实际上需要知道的是：“使用此端点记录您的客户的付款。您将返回一个事务ID，可以用来跟踪付款状态、发放退款或生成收据。大多数客户在收集付款信息后立即调用此端点。”

你看到区别了吗？一个描述代码。另一个描述解决方案。自动生成的文档无法跨越这一步，因为它们不了解上下文。它们不知道80%的用户正在构建电子商务结账系统。它们不知道最常见的错误是忘记包含幂等性密钥。它们不知道开发者通常需要将此端点与GET /payment-methods结合调用。

具有最佳API采用率的公司将自动生成作为起点，而不是终点。它们生成参考文档，然后让技术写手或真正使用API的开发者倡导者重写每一页，提供真实的上下文、真实的示例和真实的用例。这样做需要更长的时间。成本更高。但这是3%激活率与40%激活率之间的区别。

身份验证文档差距

如果让我选出我反复看到的单一最大文档失败，那就是身份验证。这是大多数开发者放弃的地方。并不是因为身份验证本身复杂——它并不复杂，而是因为文档假设了新用户没有的知识。

"如果开发者在10分钟内无法让你的API工作，他们会找到一个能工作的。你的竞争对手只需一次谷歌搜索。"

这里有一个我上个月评估的API的真实例子。他们的身份验证文档开头是：“TXT1.ai使用带JWT令牌的OAuth 2.0。从仪表盘获取您的客户端凭据，并使用授权代码流交换它们以获取访问令牌。”如果你是经验丰富的API开发者，这可能是有意义的。如果你不是？你就会碰壁。

缺失的是什么？所有的内容。在仪表盘的哪个位置我可以找到这些凭据？什么是授权代码流，为什么需要它而不是仅仅使用API密钥？成功的身份验证请求看起来是什么样的？响应包含什么？令牌的有效期是多长？过期后会发生什么？我是否需要在第一天实现刷新逻辑，还是我可以从简单的开始？

我在34种不同的实现OAuth的API中跟踪到这种模式。平均身份验证文档长达1200字。首次成功身份验证的平均时间是多少？47分钟。但有趣的是，文档最简短、最简单的API（平均400字）却拥有最快的身份验证时间（平均8分钟）。