绝佳的API设计秘诀 - DZone集成

19-09-11 banq
                   

我们构建软件的方式正在发生变化。

现在,由于API平台的激增,公司将以更快的速度推出市场并以前所未有的速度构建功能。

API经济近年来爆炸式增长,数以千计的新API进入市场并重塑了开发人员构建软件的方式。几乎所有需求都有API解决方案:支付API,通信API,运输API以及数千种。那么如何构建一个在竞争中脱颖而出的API呢?

无论您的目标是构建开源API,API平台还是API,以帮助其他开发人员与您的产品集成,有一件事使成功的API脱颖而出:您必须构建一个针对开发人员优化的API经验(DX)。

无论您是产品经理,技术联合创始人还是开发人员,您都需要将最终用户置于每个API设计决策的最前沿。通过采用这种心态,您正在为自己的用户配备使用您的服务进行创新。Facebook就是一个很好的例子。在Facebook的早期,开发人员正在他们的平台上构建游戏,但Facebook从他们的努力中获利 - 所有这些都是因为他们在社交媒体游戏平台内发展了一个强大的开发者社区。

通过授权他们构建自定义的应用程序体验(甚至是您不了解您的平台可以提供的体验),将您的API用户置于驾驶员的位置,使您在不断发展和变化的SaaS解决方案中脱颖而出。

在本文中,我们将讨论API设计的以下方面:

  1. 缩短价值时间
  2. 将您的文档视为您网站的主页
  3. 在您的API中使您的抽象一致
  4. 面向未来的API
  5. 改变是不可避免的,妥善管理

但在我们深入研究之前,值得一提的是每个API的这些桌面功能。由于这些相当简单,我们不会在本文中深入探讨它们:

  • 您的API应始终开启(99.9%正常运行时间或更高)
  • 您的API应该快速闪烁(保持响应时间较短)
  • 您的API应无缝更新(无重大更改)
  • API应该暴露构建块,而不是静态解决方案

那些下来?好的,让我们进入!

1.缩短价值实现时间

一个出色的API将缩短开发人员的价值实现时间(TtV)(即,他们从API中看到价值的时间)。即使在开发人员开始与您的API集成之前,也会缩短TtV。您可以通过允许用户在文档中测试cURL响应来证明您的API在文档中的价值 - 您可以在Nylas文档中看到这样的示例。

即使您提供测试令牌,使用第一次 - 每次一次的框架也很重要。使用测试令牌示例,大多数开发人员希望测试令牌进程完全按照规定工作,而其他人则不熟悉cURL命令的操作方式。这是优秀文档发挥作用的地方。

(1)匹配用户的期望

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

在大多数情况下,这需要在API的可用性方面采取“第一次做正确的事”的方法。您可以通过提供一个API来缩短您的价值实现时间(TtV),该API可以从第一次交互开始快速有效地解决具有挑战性的技术问题。定期检查以测试您的API,并确保第一次互动顺利,并有一个很大的“哇”的感觉。

(2)使用SDK提高效率

SDK是减少集成过程中摩擦的最佳方法之一。确保开发人员能够尽快找出API SDK集成的参数至关重要。效率既可以节省编码时间,又可以消除任何心理障碍,同时了解API如何在其选择的框架内运行。使用简单的Ruby,NodeJS或Python SDK,开发人员可以在很短的时间内构建功能齐全的集成。

虽然SDK需要时间来创建和维护,但它们可以显着改善开发人员体验并降低TtV。

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

将您的API文档视为您网站的首页。它是用户书签和开始使用的中心位置; 它应该是用户友好的,直观的,并遵循逻辑流程。

您的API文档需要具有内在的可发现性和易用性 - 就像API本身一样。Stripe是一个很好的例子。它的文档易于导航,左侧边栏上有清晰的目录,以及通过Stripe API成功收取付款的简单6步流程。

虽然确保API可用性和TtV快速做有价值的基础非常重要,但您的界面只能与文档一样可用。只有在文档易于发现时,您的文档才有用。

您的文档库应该以内置搜索功能的一致方式进行组织 - 特别是如果您的API中有许多需要全面文档的复杂元素。这意味着您的文档必须在逻辑上进行组织,可扫描,并在整个API集成过程中提供上下文覆盖。

您的文档不仅应该是可发现的,而且还应该是上下文的。换句话说,它们应该出现在每个开发人员选择的编程语言中。列出有关如何使用API​​的所有技术指南是不够的,您需要提供可帮助为特定开发人员方案提供上下文的路标。换句话说,在创建文档时,您需要使用各种可用性。这甚至可能意味着调整您的技术以满足每个用户的技术需求(SDK,自定义代码语言)。

很可能,开发人员正在使用您的技术来解决一个独特的问题,因此他们需要查看各种指南,示例和快速入门,以向他们展示证明他们可以以非常具体,可扩展的方式使用您的API 。

3.使抽象一致

开发人员友好的API需要一致性。为了优化可用性,您应该创建在API中始终抽象创意的工作流程。

您还可以使用相同的POST请求在Google和Exchange事件上获得完整的CRUD。代码中没有例外,要求开发人员以不同的方式工作,尽管Google和Exchange事件的数据模型差别很大。

另一方面,很容易过于关注一致性,这样你就会错失创新的机会。例如,可以延迟推出API的异常,这些异常可能会以抽象一致性的名义改进您的产品,因此请务必找到合理的平衡点。

4.面向未来的API

今天,世界倾向于通过JSON移入和移出数据。取决于您的受众,可能会有所不同,并且在几年内可能会有所不同。添加GraphQL API可能更好。

开发人员会查看您的API以消除其工作流程中的摩擦。如果您的API不遵循开发领域最新的无摩擦趋势,您将失去很多兴趣。虽然软件工程的趋势在不断发展,但您希望至少了解发展趋势并考虑将哪些趋势纳入您的API。例如,大多数开发人员期望来自cURL命令的JSON响应。JSON可能看起来像是明显的反应,但情况并非总是如此。

通过发送简单的JSON响应代替二进制XML和SOAP,我们能够最小化摩擦并创建更好的开发人员体验。

5.变化是不可避免的 - 你如何管理它

构建API时,更改是不可避免的。REST API是GRAPH API的前身。JSON是现代API的行业标准文件格式,但随着技术的发展,这可能会发生变化。由于改变是不可避免的,你唯一能做的就是拥抱它并尝试通过以下方式做好准备:

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

创新的数字支付提供商Stripe采用相当严格的方法来改变每次需要更改时创建API的新版本(有效地改变API的旧版本)。这要求它支持Stripe API的每个版本,从最初的概念到最新的推出。如果仓促或不正确地对API进行重大更改会产生严重的业务影响,这就是为什么有些公司选择与Stripe相同的版本控制方法。

(2)尽早和经常沟通变化

另一方面,Facebook快速而频繁地对其API进行更改 - 这让全世界的网络和移动应用程序开发人员感到高兴和/或懊恼。它非常善于提前传达这些变化(或者至少比平均值更好),因此开发人员可以做好准备,因此很少甚至没有变化会破坏最终用户的服务。如果您没有资源来构建像Stripe这样的版本化系统,那么能够很好地沟通变更是一种较低预算,较小规模的处理方式。

API版本控制可能具有不同的复杂程度。简单版本编号系统(V1,1.1,1.2及以后版本)可以很好地和相当有效地扩展。

 

                   

1