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

时间: 2019-09-16阅读: 464标签: api

如今,随着我们构建软件方式的变化,以及API平台的爆炸式激增,各大公司都必须以更快的速度构建出自己的产品、并推向市场。目前,几乎所有的软件需求都需要通过API来提供相应的解决方案,其中包括:支付类API、通信类API、以及传输类API等数千种。那么我们该如何设计并构建出一个优质的API呢?

无论您的目标是要构建一个开源的API、一种API平台、还是能帮助其他开发者与自己的产品相集成的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文档中,找到类似的示例。

即使您能够提供测试令牌(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每次都会提前通知此类变更。因此只要您的开发人员能够提前做好准备,就不至于被动地影响到最终用户的服务。可见,如果您没有实力来构建版本控制系统的话,应尽早且经常性地与各个方面沟通变更信息,这是一种更低成本、更灵活主动的处理方式。


总结

综上所述,您需要确保自己的API在第一次被试用时就能如期运行,并籍此建立与各类开发人员的信任基础与使用愿望。这虽然听起来极其简单,但是在实践中也充满了挑战。希望上述五种实践“秘籍”,能够帮助您构建属于自己的优质API,并能给开发者带来不俗的体验。

原文标题:Secrets to Great API Design,作者:Tasia Potasinski


站长推荐

1.云服务推荐: 国内主流云服务商,各类云产品的最新活动,优惠券领取。地址:阿里云腾讯云华为云

2.广告联盟: 整理了目前主流的广告联盟平台,如果你有流量,可以作为参考选择适合你的平台点击进入

链接: http://www.fly63.com/article/detial/5380

构建API的最佳编程语言是什么?

你是否正在设计第一个Web应用程序?也许你过去已经建立了一些,但是目前也正在寻找语言的变化以提高你的技能,或尝试新的东西。有了所有信息,就很难决定为下一个产品或项目选择哪种编程语言。

[探索]怎么样的参数能让 JS - API 更灵活

外在决定是否需要了解内在,内在决定是否会一票否决外在。内外结合,好上加好。 开发 API 的时候,把参数的名字和位置确定下来,函数定义就可以说是完成了。

JSON Web 令牌(JWT)是如何保护 API 的?

你可以已经听说过 JSON Web Token (JWT) 是目前用于保护 API 的最新技术。与大多数安全主题一样,如果你打算使用它,那很有必要去了解它的工作原理(一定程度上)。问题在于,对 JWT 的大多数解释都是技术性的,这一点让人很头疼。

vue-next 函数式 api

在分享 vue-next 各个子模块的实现之前,我觉的有必要比较全面的整理下 vue-next 中提出的函数式 api,了解这些的话,无论是对于源码的阅读,还是当正式版发布时开始学习,应该都会有起到一定的辅助作用

Notification API,为你的网页添加桌面通知推送

其实,MDN 的说明已经可以让我们很清楚知道 Notification 的作用。Notification 能够为用户提供异步的桌面消息通知,即使你缩小浏览器或是活动在其他标签页,只要调用该 Api 的标签页没被关闭

Vue 3.0 的 Composition API 尝鲜

虽然 Vue 3.0 尚未发布,但是其处于 RFC 阶段的 Composition API 已经可以通过插件 @vue/composition-api 进行体验了。接下来的内容我将以构建一个 TODO LIST 应用来体验 Composition API 的用法。

SDK 与API之间的关系和联系

SDK(Software Development Kit,软件开发工具包)一般都是一些软件工程师为特定的软件包、软件框架、硬件平台、操作系统等建立应用软件时的开发工具的集合,比如提供安卓开发工具、或者基于硬件开发的服务等。也有针对某项软件功能的SDK

Vue3 Composition API 如何替换Vue Mixins

想在你的Vue组件之间共享代码?如果你熟悉 Vue 2 则可能知道使用 mixin ,但是新的 Composition API 提供了更好的解决方案。在本文中,我们将研究mixins的缺点,并了解Composition API如何克服它们

webService和Restful

restful是一种架构风格,其核心是面向资源,更简单;而webService底层SOAP协议,主要核心是面向活动;两个都是通过web请求调用接口

HTML5常用API

该API可以用来检测页面对于用户的可见性,即返回用户当前浏览的页面或标签tap的状态变化。 在最小化浏览器、切换tap页面时生效.(如需对app中几个webview进行切换操作时

点击更多...

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!

文章投稿关于web前端网站点搜索站长推荐网站地图站长QQ:522607023

小程序专栏: 土味情话心理测试脑筋急转弯幽默笑话段子句子语录成语大全运营推广