报名参加CloudWeGo黑客松,奖金直推双丰收! 了解详情
写点什么

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

  • 2013-11-28
  • 本文字数:2369 字

    阅读完需:约 8 分钟

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

2013-11-28 07:031725

评论

发布
暂无评论
发现更多内容

校招前端一面必会vue面试题指南

bb_xiaxia1998

Vue

阿里云前端专家冯军:前端用户体验该如何优化

云布道师

阿里云

2023我的前端面试小结

loveX001

JavaScript

web前端技术应该怎么规划学习?

小谷哥

功能上新|一键归因分析,快速洞察指标波动原因

Kyligence

指标中台 归因分析

校招前端二面常考react面试题(边面边更)

beifeng1996

React

Koordinator v1.1发布:负载感知与干扰检测采集

阿里巴巴云原生

阿里云 云原生 Koordinator

深圳大数据培训机构怎么选

小谷哥

OpenHarmony系统使用gdb调试init

OpenHarmony开发者

openha

海量数据同步首选 SeaTunnel Zeta 引擎正式发布!

Apache SeaTunnel

大数据 开源 apache 社区 Apache SeaTunnel 数据集成平台

一种多维数据库的数据事务专利解读

元年技术洞察

数据中台 数字化转型 专利解析 多维数据库

如何在Java程序中合并和拆分Excel文档

Geek_249eec

Java Excel 工作表

假如问:你是怎样优化Vue项目的,该怎么回答

bb_xiaxia1998

Vue

ZooKeeper 避坑实践:SnapCount 设置不合理导致磁盘爆满,服务不可用

阿里巴巴云原生

zookeeper 阿里云 云原生

基于ERNIELayout&pdfplumber-UIE的多方案学术论文信息抽取

汀丶人工智能

nlp 信息抽取 2022年终总结 2023新展望

前端培训机构如何学习开发技术

小谷哥

Rancher RFO 正式 GA

openEuler

Linux 开源 Kubernetes 操作系统 rancher

2022年是最烂的一年吗?我的2022年终总结

Zhendong

总结 年终总结 2022年终总结

经常会采坑的javascript原型应试题

loveX001

JavaScript

ARM 算子性能优化上手指南

MegEngineBot

深度学习 开源 性能优化 MegEngine

如何通过C#/VB.NET将格式应用于 Word 中的字符

在下毛毛雨

C# .net word文档 字符格式

React循环DOM时为什么需要添加key

beifeng1996

React

前端一面常考react面试题

beifeng1996

React

注意这八个容易损坏LED显示屏的情况

Dylan

LED显示屏 全彩LED显示屏 led显示屏厂家

前端高频vue面试题总结

bb_xiaxia1998

Vue

尚硅谷&腾讯云EMR实时数仓教程发布

小谷哥

React的useLayoutEffect和useEffect执行时机有什么不同

beifeng1996

React

深入理解JS作用域链与执行上下文

loveX001

JavaScript

js函数柯里化-面试手写版

helloworld1024fd

JavaScript

AIGC最近很火,给大家推荐一个已经有1000位开发者使用的中文aigc开源模型,包括ai画图、ai聊天

AIGC布道者

人工智能 机器学习 AI AIGC AI绘画

2023我的前端面试小结

loveX001

JavaScript

API设计中人的因素:专访Apiary的Jakub Nesetril_软件工程_Saul Caganoff_InfoQ精选文章