何为 API 开发体验，为何其如此重要

API 开发体验是一个相对较奇特的关注点，之所以受到关注，是因为这样的体验能提高 API 的程序设计水平，当开发者在编写程序的时候，夯实无缝的开发体验是多么的重要，不但能帮助程序员提高编程效率，还能让开发人员站在终端用户的角度来实现功能目标。

Jeremiah Lee Cohick 是 Fitbit 公司的一名工程师，对较为广泛的开发体验（DX）领域里的用户体验、框架 API 体验有着特别的理解和感受。DX 包括程序员和他们的开发平台之间的多方面关系，如信任、教育、工具和平台的可用性等等。需要特别强调的是，Cohick 将“API 体验”直接描述为“API 用户体验”，这种体验上的转变最终会演变成开发阶段影响编写代码的关键部分。在 2014 年举办的一次 Web Directions 大会上，Cohick 在演讲中就明确定义了可达到 API 卓越目标的四个关键部分：

• 功能性：通过 API 能够解决什么问题这一过程就能看出 API 的价值所在。有用的 API 体验除了要努力而有效地解决一个问题之外，还应该超乎想象的将问题解决。
• 可靠性：合理的 API 一定要具备类似可用性、可扩展性、稳定性等这样的非功能性特征才是完美的，因为这些特征能够帮助开发者团队建立信任感，并代表一种必须的元素来驱动开发人员使用 API。
• 可用性：API 如何很好的通过自我感知的条件去发现和了解自己的功能？这个 API 在开发者轻松地创建测试过程中是不是很轻便、智能？而且在错误处理这一流程中又能提供哪些支持呢？这些都是考核 API 可用性的指标。
• 舒适性：一个 API 如何能给开发者一种这次用过了下次还想用的快感？

根据 Cohick 所说的，一旦 API 具备了上述所有的必选条件，其给开发者带来的是非同凡响的开发体验；相反，缺失某一特征或者存在明显的纰漏都将是给开发者带来痛苦和混乱的根源。

就职于 Intel Mashery 的产品负责人 Amit Jotwani 说，和 API 开发相关的人群确实应该认认真真的对待开发者体验这一事。下面是他给出的创建伟大 API 体验的十个步骤：

• 尽量保持简单。
• 避免将营销术语用在 API 程序里，同时还要明确说明，开发者在使用这个 API 的时候哪些功能是可以随时关掉的！
• 整体简洁、快速登录，此外在 API Key 和服务选项的管理上力求简单。
• 快速设置，理想情况下，只需 5 分钟就能创建一个“Hello World”App。
• 提供快速被用开发的 API Key，以此缩短长等待时间。
• 明确了成本和限制条件，不要创造过高的期望，还要提供免费试用。
• 提供长期性的完整文档，定期更新，并避免使用 PDF 格式。
• 必须提供交互式文件，如 Mashery API Explorer 和 Klout 交互式控制台，这些都能帮助开发者更容易发现和了解 API。
• 显示代码，给出清晰简明的使用 API 方式的例子。
• 鼓励开发人员在例如 Stack Overflow 和 Twitter 等渠道里分享自己的经验、心得。

根据 API Academy 公司的 API 设计主管 Ronnie Mitra 的说法，多数咨询公司帮助各种开发组织改善 API 性能，API 体验已经开始能够识别开发者了。想要创造一个优良的 DX，应该先设定为四个关键目标：

• 协助排除故障（e.g. 提供有用的错误信息）
• 简化修缮管理（e.g. 推出 API 版本控制策略）
• 提高可视性（e.g. 提供日志和使用访问权限）
• 建立信任关系（e.g. 传达一种稳定而长久的感觉）

在 Stockholm 举办的 API 大会上，Mitra 提出了一个框架设想，类似于 Cohick 之前帮助设计的伟大 API，其设想里的 API 主要有三大支柱：功能性、可用性和体验。在这种情况下，可用性将关注的焦点从功能性 / 可靠性转移到开发者身上，旨在帮助 API 更易于使用。体验涉及到开发者对所有的 API 交互有一种什么样的感觉，而且这种体验是建立在功能性和可用性基础之上的。

Mitra 还说，要想提供一个优异的 API 体验，关键点在于要深入理解它的最终用户，决不能闭门造车出门不合辙。其实这可以通过给不同的、典型的 API 用户进行重新定义就能搞清楚。

如果你不知道谁将会使用你创造出来的 API，你根本没有办法设计 API 的可用性。

一旦决定确定之后，API 的可用性方面可以通过几个维度估算出来，原理是基于在微软工作的 Steven Clarke 提出的理论：

• 调用比：在执行任务的时候，API 能为开发者调用多少次？
• 结构：所需数据有多深？噪音比的信号是什么？
• 导航：从一个结果转移到另一个结果有多困难？定位所需的数据多少难度？
• 开发堆栈大小：需要多少个新组件？
• 第一次调用：一个新用户如需执行第一次 API 调用，需要多少时间？
• 错误：修复一个错误很难做到么？错误的本质是什么？

同样，API 体验提供了以下几个方面：参与、快感、熟悉、信任和安全，这些方面都能指导设计整个开发的全过程。最重要的是，上面提到的这几个方面都是 API 高可用性质量的直接体现。

查看英文原文： What is API Developer Experience and Why It Matters

感谢张龙对本文的审校。

给InfoQ 中文站投稿或者参与内容翻译工作，请邮件至 editors@cn.infoq.com 。也欢迎大家通过新浪微博（ @InfoQ ， @丁晓昀），微信（微信号： InfoQChina ）关注我们，并与我们的编辑和其他读者朋友交流（欢迎加入 InfoQ 读者交流群）。