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

时间: 2019-09-16阅读: 129标签: 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.休闲娱乐: 网页游戏  直播/交友   H5游戏

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

webService和Restful

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

使用 JS 来动态操作 css ,你知道几种方法?

JavaScript 可以说是交互之王,它作为脚本语言加上许多 Web Api 进一步扩展了它的特性集,更加丰富界面交互的可操作性。这类 API 的例子包括WebGL API、Canvas API、DOM API,还有一组不太为人所知的 CSS API

在 Node.js 上运行 Flutter Web 应用和 API

大量的跨平台应用开发框架,使你可以编写一次代码,然后在 Android,iOS 等多个平台上甚至在台式机上运行。你可能听说过一些流行的框架,例如 Ionic,Xamarin 和 React Native。另一个相对较新的框架是 Flutter

vue-next 函数式 api

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

Moment.js常用API速查

日常开发经常会用Moment.js来处理时间,现对频繁使用的几个API做下整理,以便日后查阅。

SDK 与API之间的关系和联系

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

基于 React 和 Redux 的 API 集成解决方案

在前端开发的过程中,我们可能会花不少的时间去集成 API、与 API 联调、或者解决 API 变动带来的问题。如果你也希望减轻这部分负担,提高团队的开发效率,那么这篇文章一定会对你有所帮助。文章中使用到的技术栈主要有:

API文档管理工具折射出的技术视野

网上看到不少关于如何提升技术视野的讨论,但却没有人给出定义,到底什么是技术视野?所谓技术视野,就是看问题时所能切换的不同角(维)度。下面就以API管理工具

Node.js中Streams

NodeJs流以难以使用而闻名,甚至更难理解。 好吧,我给你带来了好消息 - 现在已经不是这样了。多年来,开发人员创建了许多软件包,其唯一目的是为了更容易的使用流。 但是,在本文中,我将重点介绍NodJs 原生的流API。

ACE Editor在线代码编辑器的API使用文档

ACE 是一个开源的、独立的、基于浏览器的代码编辑器,可以嵌入到任何web页面或JavaScript应用程序中。ACE支持超过60种语言语法高亮,并能够处理代码多达400万行的大型文档

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

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

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