如何让 API 对开发者更友好
浏览：2
巴克励步
最近和几个做开发者工具的朋友聊，大家都不约而同地提到一个痛点：API 做出来了，文档也写了，可开发者就是不买账。我翻了不少案例，发现很多团队把精力都花在接口的稳定性上，却忽略了“开发者体验”这个软实力。说白了，API 文档不只是说明书，它本身就是产品的一部分。一个好的 API 文档，能让开发者从“这是啥？”秒变“我懂了”，这背后是信息架构和内容表达的设计。Baklib 在 API 文档建设上的思路，
最近和几个做开发者工具的朋友聊，大家都不约而同地提到一个痛点：API 做出来了，文档也写了，可开发者就是不买账。我翻了不少案例，发现很多团队把精力都花在接口的稳定性上，却忽略了“开发者体验”这个软实力。说白了，API 文档不只是说明书，它本身就是产品的一部分。一个好的 API 文档，能让开发者从“这是啥？”秒变“我懂了”，这背后是信息架构和内容表达的设计。Baklib 在 API 文档建设上的思路，就是帮你把这些细节做到位，让技术内容既专业又易懂。
了解你的开发者
如果你想创建对开发者友好的 API，你就应该了解你的开发者。
这当然不是什么惊天动地的说法，但它简单描述了过程中不可避免的一部分。
如果你开始把 API 看作你的产品，把开发者看作你的客户，就很容易理解为什么你应该努力了解你的开发者。
💛🧡🧡客户评价：Baklib正在解决几个关键与文档和知识库管理相关的问题： -Baklib为我们提供了一个集中式知识库，简化了访问我们所有的技术文档、常见问题解答和用户指南。这已经改善了效率，并确保每个人都能获得最新的信息。 -随着我们公司的全球扩张，提供多个文档语言已经变得必不可少。Baklib的多语言支持使我们能够创建和管理各种语言的内容，制作我们的文档面向更广泛的受众，并支持我们的国际增长。
一个好的销售人员了解他们的目标受众、他们想要从产品中得到什么、他们喜欢什么，以及如何提供满足他们需求的产品。
此外，软件开发者并不是一个同质的群体，正如产品设计师兼软件工程师 Mike Kelly 指出的那样：
实际上，有无数种形式的开发者，每种都有自己的一套约束和需求。
开发者拥有不同的技能组合和知识水平，来自不同的行业，使用不同的技术——这仅仅是你应该考虑的几个因素。
根据 Christina Voskoglu 在 SlashNation 上的文章，第 19 次开发者经济学调查显示，近 90% 的开发者使用 API。
这意味着全球数百万开发者中的大多数都在使用 API，而你可能无法提供一种万能解决方案来满足他们所有的需求。
那么，你能做什么呢？你可以专注于那些实际使用你 API 的开发者。
一个有用的方法是采用一个众所周知的营销实践——创建用户画像。
以下是经验丰富的数据分析师 Janitra Ariena Sekaputri 对用户画像的定义：
换句话说，你可以收集关于 API 用户的数据，比如他们的技术偏好、行业背景、人口统计信息等，然后创建一个具有这些特征的虚拟用户。
你会创建多少画像取决于使用你 API 的开发者的多样性。
然而，你最终应该得到类似这样的东西：
你可以看到“Kyle Matthews”拥有的技能、他用于个人发展的内容、他喜欢的产品、他的工作方式等。
当一个用户群体的所有相关信息都摆在你面前时，这可以极大地帮助你调整你的 API，使其更易于你的开发者访问。
拥有详细的 API 文档
当开发者决定使用你的 API 时，他们通常会直接查看你的 API 文档。
这完全合理。即使是有经验的开发者在有效使用软件接口之前，也需要了解它们。
文档应该提供开发者开始使用 API 所需的一切信息，从基础信息和教程到请求和响应列表、端点等。
这样，开发者就不会浪费时间寻找使用 API 的最佳方式，也不会错过它们的全部潜力。
正如我们提到的，详细的文档应该首先向开发者提供基础知识，因此“快速开始”部分是必不可少的。
SendGrid 的 API 文档中就有这样的部分。它提供了 API 的概述，包括如何使用 SendGrid API 发送电子邮件的说明。
如你所见，说明既直接清晰又详细。
开发者立刻被告知他们需要拥有一个 API 密钥，然后他们获得一个可以复制的代码片段，以及剩余步骤的逐步说明。
这是一个精确而简洁的入门教程，在 SendGrid API 文档的其余部分中，你也可以找到同样对细节的关注。
例如，如果你想学习如何过滤所有消息，你会得到左侧的特定查询说明和右侧的多种编程语言的代码。
这样，开发者既获得了关于过滤所有消息可能性的信息，也获得了可以立即用于尝试该功能的所有必要信息。
为了创建和发布详细的 API 文档，你需要一个出色的工具。幸运的是，我们自己的解决方案 Baklib 可以满足你所有的需求。
你可以创建一个全面的快速入门指南，就像下面 Breadwinner 的指南一样，并用截图和其他视觉效果丰富它，使其更易于遵循。
当然，没有代码示例就不可能有详细的 API 文档。
使用 Baklib，你可以用最流行的编程语言创建代码示例，并直接将它们插入文档中。
总而言之，API 文档对你的用户至关重要。
开发者从文档中获得指导越多，他们就越容易使用你的 API。
如果你想让他们对开发者友好，就尽可能详细地记录它们。
关注易采纳性
开发者在工作日有很多事情要做，所以他们欣赏任何能节省时间和精力的事情。
除了编写代码、测试代码、处理 bug、与客户沟通、与团队成员协作、参加会议以及许多其他职责之外，花几个小时试图弄清楚 API 显然不是他们渴望做的事情。
然而，如果你让你的 API 如此易于访问，以至于他们可以在短时间内启动并运行，他们很可能会乐意使用它们。
开发者在工作中已经非常依赖 API。
根据 2022 年 API 状态报告，62% 的人比前一年更依赖 API，69% 的人预计在 2023 年会更依赖 API。
那么，为什么不让你 API 的采纳过程更简单呢？
你可以做的第一件事是简化注册过程。
例如，国家公园服务 API 提供开发者可以在其应用、地图和网站中使用的数据。
你需要一个 API 密钥才能访问他们的 API，但获取它非常容易——只需提供姓名和电子邮件地址。
除了简单的注册，对开发者友好的 API 还应该提供特定语言库。
当然，你不可能为所有编程语言提供库，但至少应该为最流行的几种提供资源。
例如，Plaid 提供了五种编程语言的库。
这样，开发者可以选择他们偏好的语言，从而更容易采纳你的 API。
考虑一下开发者在你的 API 遇到麻烦时会发生什么。你应该准备好一个清晰的解决问题的方法，并提供高质量的支持。
无论可能出现什么问题，开发者都应该知道他们有资源来排除故障。
这就是 Giphy 为其 API 设立常见问题解答部分的原因。
它涵盖了开发者可能遇到的最常见问题，以便他们快速找到答案。
如果常见问题解答中没有涵盖问题，开发者可以随时联系 Giphy 客户服务寻求帮助。
这种支持使 API 采纳更容易，这正是你鼓励开发者依赖它们所需要的。
遵循 API 命名约定
虽然命名 API 似乎是一项简单的任务，但有一些约定你应该遵循，以使开发者的工作更容易。
命名 API 很重要，因为开发者经常依赖名称来评估他们将处理什么样的信息。
因此，命名应该使事情清晰，并最大限度地减少混淆的可能性。
如果做得不好，可能会误导开发者，导致他们浪费时间和精力，最终产生挫败感。
让用户感到沮丧不会让他们更愿意使用你的 API。
这就是为什么有一些既定的命名约定你应该遵循。
例如，看看下面的 Google Maps 请求。
该请求展示了建议使用的某些 API 命名约定。
其中之一是使用复数名词而不是动词来指定资源。
在上面的例子中，Google 使用了 “directions” 而不是 “getDirections”、”createDirections” 或其他变体。
