解锁设计优质API的五种秘籍

无论您的目标是要构建一个开源的API、一种API平台(https://dzone.com/articles/what-is-an-api-platform)、还是能帮助其他开发者与自己的产品相集成的API，您都必须努力优化开发者的API体验(DX)。

无论作为产品经理，还是技术开发人员，您都需要在每个API的设计决策上，充分考虑到最终用户，只有这样他们才会愿意使用您开发出的API。在此方面，Facebook就是一个非常好的例子。在早期，他们在社交媒体的游戏平台上就开辟了一个强大的开发者社区，以方便大家构建出不同的游戏。当然Facebook也能够从中获利。

为了能够在不断变化与发展的SaaS环境中脱颖而出，您可以通过授权用户构建自定义的应用程序(甚至是在您所不了解的平台上提供完美的使用体验)，来让他们产生所谓“驾驭的快感”。

一般而言，普通API应当具有如下基本特性：

• 具有一定的鲁棒性，以保证99.9%(或更高)的正常运行时间
• 具有快速响应能力，或响应耗时较短
• 能够无缝更新，或无需引入重大变更操作
• 能够公布各个构建的模块，而非一个静态固化的解决方案

下面，我们将和您深入讨论设计优质API所应当注意的五个方面：

1. 缩短宝贵的时间
2. 将您的文档置于网站的主页
3. 在API中保证抽象的一致性
4. 设计面向未来的API
5. 妥善管理好潜在的变更

1.缩短宝贵的时间

一个优质的API应当能够缩短开发人员的宝贵时间(TtV)。也就是说，在开发人员开始与您的API集成之前，就能够根据对应的用户手册，测试有关cURL(译者注：一种利用URL语法，工作在命令行里的文件传输工具)的响应，以证明API自身的使用价值。您可以在Nylas文档(https://docs.nylas.com/reference)中，找到类似的示例。

即使您能够提供测试令牌(test tokens)，使用一通百通(first-time-every-time)的框架也非常重要的。通过使用测试令牌的相关范例，那些不熟悉cURL命令操作的开发人员，也能够像其他人那样来测试令牌的进程，检查API是否能够完全按照设定运行下去。此处正好需要配有良好的文档说明。

符合用户的期望

在构建API时 ，请牢记一个问题：该API是否完全符合，用户期望在第一次尝试时所执行的操作?

在大多数情况下，您需要在API的实用性方面采取“首次把将正确的事做对(do the right thing right the first time)”的方法，以保障所提供的API的确能够缩短开发者宝贵的时间(TtV)。从开发人员第一次交互开始，该API就能够快速有效地解决那些具有挑战性的技术问题。因此，请定期检查并测试自己的API，确保用户能够顺利地完成首次互动，并为后续使用树立信心。

使用SDK来提高效率

SDK是减少集成过程出现“摩擦”的合适方法之一。它对于确保开发人员能够尽快地找出API中的SDK集成参数，也是非常重要的。通过使用简单的Ruby、NodeJS或Python SDK，开发人员可以在较短的时间内，了解API是如何在其选择的框架内运行的，进而高效地完成功能齐备的集成。记住：虽然SDK需要花费一定的时间来创建和维护，但它们的确能够显著地改善开发人员的体验、并降低他们的TtV。

2.将您的文档视为网站的主页

由于在您的首页上就能获取API的相关文档，因此开发人员可以将其加入浏览器的书签、或放置到显著的位置。当然，您的API文档不但要直观且用户友好，而且要能够遵循一定的逻辑流程。

说到API文档的易获取性和易用性，Stripe(https://stripe.com/)就是一个很好的例子。如下图所示，它的文档易于导航，左侧边栏上有着清晰的目录，右侧则是Stripe API成功付款的简单6步流程：

如果您的API中有许多需要全面进行文档解释的复杂元素，那么您的文档库应该通过内置的搜索功能，方便开发人员进行遍历查询。同时文档也应当以一致性的方式进行逻辑性组织，并在整个API集成的过程中做好针对上下文的内容覆盖。

此处的“上下文”是指，让每一位开发人员都能选择不同的编程语言。可见，列出针对某一种语言的API使用技术指南是不够的，您的文档需要具有不同语言的适用性，甚至是满足某些特定开发技术(各种SDK、或自定义代码语言)的解决方案。毕竟，某位开发人员很可能正在使用您的API技术，去解决某个独特的问题，因此他们需要查看与之相关的各种指南、示例、以及快速入门。同时，这也是展示与证明您的API具备全面性和可扩展性的良机。

3.在API中保证抽象的一致性

为了方便开发人员的使用，并提高API的实用性，您需要在API中保证抽象工作流的一致性。

您可以使用相同的POST请求，在不同的Google和Exchange事件中获得完整的CRUD(增加Create、读取Read、更新Update和删除Delete)。尽管Google和Exchange不同事件的数据模型差别较大，但是开发人员没有必要以不同的方式，来开展代码的编程工作。

当然，您不必过于苛求抽象的一致性，而刻意忽略了个别特例。例如，您可能为了顾及产品的通用一致性，而未能及时地抛出在某种环境下API的异常信息，导致开发人员无法跟踪到程序的某项缺陷。因此，请务必找到一个合理的平衡点。

4.设计面向未来的API

如今，业界倾向于通过JSON来导入和移出数据。但是在不久的将来，大家也许会大量使用到GraphQL API(译者注：既是一种可用于API查询的语言，又是一种满足数据查询的运行时)。开发人员通过检查您的API，以消除其工作流程中的各种“摩擦”。因此，如果您的API无法遵循开发领域的最新无摩擦(frictionless)趋势的话，那么您的API很可能会失去竞争力。例如，虽然大多数开发人员期望用JSON来响应cURL的命令。但是您可以做得更加丰富一些。通过发送各种简单的JSON响应，来代替二进制的XML和SOAP，这样不但能够最小化摩擦，还能够为开发人员创造更好的体验。

5.妥善管理好潜在的变更

在构建API时，更改往往是不可避免的。由SOAP API引出了REST API，而REST API则是GRAPH API的前身。JSON虽然是如今API的行业标准化文件格式，但随着技术的发展，面对任何可能出现的变化，你需要从如下方面来妥善管理自己的API：

从第1天开始就内置版本控制

创新的数字支付提供商Stripe就采用了相当严格的管控方法。为了避免由于仓促或不正确的API变更，对于业务产生的严重影响，他们从最初的概念到最终的推出，都实施了严格的Stripe API版本控制，并保证向后兼容性。在具体实践中，您对于API的版本控制可能不如成熟企业那样复杂和专业，但是您完全可以使用简单的版本编号系统(如：V1、V1.1、V1.2等)，来更好地、有效地实现版本扩展与管控。

尽早和经常性地沟通变更

另一方面，作为业界的大厂，Facebook频繁地对其API进行着变更和调整，这让全世界的网络和移动应用开发人员经常爱恨交织。不过，Facebook每次都会提前通知此类变更。因此只要您的开发人员能够提前做好准备，就不至于被动地影响到最终用户的服务。可见，如果您没有实力来构建版本控制系统的话，应尽早且经常性地与各个方面沟通变更信息，这是一种更低成本、更灵活主动的处理方式。

总结