BT

如何利用碎片时间提升技术认知与能力? 点击获取答案

API设计中人的因素:专访Apiary的Jakub Nesetril

| 作者 Saul Caganoff 关注 1 他的粉丝 ,译者 张卫滨 关注 13 他的粉丝 发布于 2013年11月29日. 估计阅读时间: 7 分钟 | Google、Facebook、Pinterest、阿里、腾讯 等顶尖技术团队的上百个可供参考的架构实例!

API的设计与描述并不仅仅是机器之间的技术接口。API设计和描述并不仅仅是机器间的技术接口。  Apiary的联合创始人兼CEO Jakub Nesetril指出API描述的真正使用者是开发人员,需要考虑到开发人员的参与、可用性以及交流等方面。最近,就API设计以及API工具和工作流,我们与Apiary进行了交流。

InfoQ: Jakub,你最近在API Strategy会议做了关于API设计最佳实践的演讲。你提到了“构建API并没有绝对正确的方式”。能谈一下你的这一理念吗,它是如何影响Apiary正在做的事情的?

JN::长期以来,API被视为两个电脑程序之间的接口。实际上,API是开发人员之间的接口——也就是真实的人之间。如果开发人员不了解怎样使用API,那么一切都完蛋了——你的项目肯定会失败。

API(以及更通用意义上的软件接口)非常类似于UI设计:它受到时尚周期的影响,并且不同的文化背景会有差异(在编程中,指的就是语言和框架的文化),对此很容易形成成见,但是针对什么是正确的设计,没有人能达成共识。

探寻“唯一正确的”UI设计是很愚蠢的做法,与此类似,API设计中也没有唯一的金科玉律。但是,有一些技术可以改变既有的主观性。在UI界面的演化中,我们看到近十年来,出现的趋势是关注以用户为中心的设计和用户体验。我们需要将这种方式拿到API开发之中,与客户和利益相关方实现敏捷、快速集成以及紧密的反馈环路。

InfoQ:现在有很多的API描述标准可供采用,包括你自己的API Blueprint。有一些是基于JSON、Markdown、YAML或XML的。你认为哪种方式最好呢?相对其他可选方案,是什么促使你选择了Markdown呢?

JN: 当Apiary成立的时候,XML、JSON以及YAML格式就已经存在了,我们曾经努力尝试不引入新的格式。但我们强烈感觉到这些语言太复杂了,尤其是考虑到其他角色——如技术文档编写人员或API的使用者——要参与进来的时候。当它们要携带大量人类可读的文本内容时会相当繁琐,但是好的API文档一般都会包含这样的信息。

我们寻找一种在开发人员内部比较流行的格式,它能够用来编写结构化的数据,同时又能书写成段的文字。我们想找一种人类很易于读写的形式。希望它能够很容易被技术人员和非技术人员所理解。多年以来,markdown几乎被所有的开源项目所使用,同时也是GitHub Pages和Jekyll出版系统的核心。开发人员已经使用它很多年了。

InfoQ:有些开发人员倡议将超媒体(hypermedia)作为契约式API开发的可选方案。这个问题似乎已经有很显然的答案了,但是关于契约API和无契约API,你是怎么看的?

JN: 我们可以看到超媒体有很大的潜力,但是到目前为止的推动力还是很有限。超媒体的问题在于采用情况。如果能够被广泛采用,我们可能会看到在API的使用方面会有快速的增长,但是契约的作用依然存在,它促成了校验、自动化测试以及工具。如果没有更好的工具支持,这种状况还会持续下去。但是有一些很优秀的人正在完善工具的功能,所以我们将来会看到它的进展。

InfoQ:针对基于blueprint的API实现,你最近建立了Dredd工具进行自动化测试。在API设计和开发方面,你似乎在尝试特有的工作流程。能描述一下吗?

JN: 在过去的十年间,软件开发有了一定的转变,从传统、静态的瀑布设计转变为更为敏捷的迭代。在敏捷中,我们看到了自动化测试、代码覆盖率以及持续集成这样的事情。但是在API和接口契约方面,我们看起来依然处于1999年代——预先设计、规模宏大的开发工程、陈旧的文档、没有代码覆盖率、没有持续集成。在Apiary,我们正在试图改变这一点。

在这方面,Dredd就是一个很好的例子。所有的开发人员都知道单调的、易出错的手工任务应该自动化执行。确保API文档处于最新的状态就是一项这样的任务。每个人都讨厌维护文档。借助于Dredd,我们可以将代码覆盖情况转移到API文档之中,这种方式能够与任何已有的持续集成提供商兼容。

InfoQ:开发人员的参与(engagement)看起来是API采用和成功的“秘籍(secret sauce)”。在开发人员的参与方面,每个人所缺失的是什么呢?

JN: 对可用性以及授权的关注依然是很少的。如果你看一下所有成功的API项目(以及更普遍来讲,以开发人员为中心的公司),它们的产品中都有很强大的品牌、很好的用户体验,它们允许用户所做的事情超出了用户最初的想象。这不是火箭技术,但是更加难以重新创造。设身处地为用户着想并不是很容易获得或通过训练就能得到的技能。这就是为什么Apiary的很多API设计会将相关人员聚集在一起:API设计人员、API开发人员以及API使用人员,创造一个环境让这些人很容易地进行协作。

InfoQ:Apiary有25,000在开发的API,你有没有规划利用一下这个市场地位,比如说创建API市场或仓库?

JN: 这个数字每周都在增长,所以很难进行精确统计。我们有35,000个 API,并且这一数字还在攀升。就在一年前,行业分析还曾经严肃地讨论世界上的API数量一共是50,000或80,000。现在我们知道,这个数字要大得多得多。尽管Apiary的快速增长只是过去12个月内的事情,但是行业内的大多数人都在使用机构提供的或自定义的工具。这里面还有很大的成长空间。

我们只关注一件事——只做我们能做好的——那就是帮助开发人员的工具。API市场或仓库的理念看起来很吸引人,但是我们并没有看到它能够带来的附加价值。

Apiary Inc.总部位于旧金山,工程人员位于捷克共和国的布拉格。它由Jakub Nesetril和Jan Moravec创建,并在2012年底发布了API设计平台的公测版,这是一个创新性的产品。到目前为止,Apiary已有超过35,000个API,这是世界范围内最大的一个API集合。它的早期客户是Akamai或GoodData的开发人员门户。我们最近与Jakub Nesetril就API设计、描述、工具以及测试进行了交流。

原文英文链接:The Human Aspects of API Design: An Interview with Apiary's Jakub Nesetril

评价本文

专业度
风格

您好,朋友!

您需要 注册一个InfoQ账号 或者 才能进行评论。在您完成注册后还需要进行一些设置。

获得来自InfoQ的更多体验。

告诉我们您的想法

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

AmyPI API市场(amypi.ramytech.com) by Brian Wang

amypi.ramytech.com 是目前中国国内一流的API仓库,欢迎访问

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

1 讨论

登陆InfoQ,与你最关心的话题互动。


找回密码....

Follow

关注你最喜爱的话题和作者

快速浏览网站内你所感兴趣话题的精选内容。

Like

内容自由定制

选择想要阅读的主题和喜爱的作者定制自己的新闻源。

Notifications

获取更新

设置通知机制以获取内容更新对您而言是否重要

BT