转载

JSON API 1.0 核心开发者自述 | 你所不知道的那些技术细节

2013年5月， Yehuda Katz 完成了JSON API( 英文，中文 ) 技术规范的初稿。事情就发生在 RailsConf 之后，在那次会议上他和 Steve Klabnik 就 JSON 雏形的技术细节相聊甚欢。在沟通单一 Rails 服务器库—— ActiveModel::Serializers 和单一 JavaScript 客户端库—— Ember Data 的强烈呼声下，JSON API 应运而生(关于这段历史，我在2013年2月第一届 EmberCamp 上有一个演讲，感兴趣的可以去看一看)。

打造任何客户端和服务器库都能运用的技术规范格式，Yehuda 和 Steve 在用户的痛点中看到了这件事的价值所在。关键的一点是，这样一种技术规范要能并行发展，而不是限制在最初的应用对象上。结果是，JSON API 同时受到了来自 Ember 和 Rails 圈里圈外开发者的影响，并发展成为能够迎合更大市场的强有力 spec。经过两年的酝酿、四轮备选发布方案、Git 上数百个 pull request 和无数的争议探讨，JSON API 终于推出了 1.0 版本。

在这个 JSON API 生命的关键点，有必要回顾一下它是如何走到 1.0，将来又该何去何从？首先，我们来说说 JSON API 有什么特别之处……

雄心勃勃的 JSON API

JSON API 在目标和视野上颇具野心：它不仅定义了一种媒体类型 (application/vnd.api+json) ，还制定了规则用 HTTP来抓取和修改此种媒体类型呈现的内容。从这个角度来说，JSON API 和 Collection + JSONspecification 有点像，但显然它比后者的视线更广。

JSON API 让设计和搭建一个 API 变得标准化，这样一来开发者能够更专注于应用本身的设计。

目标

那么根据 JSON API 你会搭建出什么样的 API 呢？它自己是这么说的：

JSON API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

从 JSON API 的设计中这些特点是显而易见的。诸如复合文档(compound documents)、稀疏字段集 (sparse fieldsets)和多字段排序(multi-field sorting)等等这些功能，使得客户端能够从服务器那里精确地请求获得他们需要的数据而没有别的杂七杂八的东西。

比如我们来想象一个博客API，以文章、评论和用户作为它的来源。那么客户端也许会发送如下请求：

GET /articles?include=comments,author&fields[people]=first-name,last-name&sort=-date

上述请求将会抓取所有文章及它们的评论和作者。用户来源（在这里是作者）只返回名和姓。文章集合会根据日期排序，日期越近越靠前。服务器把所有结果整合到一起返回一个单一的响应文档，或者分页。JSON API 还定义了分页链接如何返回，使任何兼容客户端都可以读懂。

聚焦超媒体

Steve Klabnik 对 JSON API 功不可没，他不但热衷于制定标准，作为超媒体的拥趸他自己撰写了有关超媒体 API 的书。

多亏了 Steve，我们才有可能用 JSON API 来搭建超媒体 API。在 JSON API 文档中可以添加链接，并且定义来源的 canonical URL。客户端可以从 API 中扒到链接，就像浏览器可以从 HTML 中扒到链接。去除了对 URL 硬编码的需要，客户端和服务器的耦合变得越来越松散，各自发展变得容易。

为什么是JSON API

Anti-Bikeshedding 武器

JSON API 强大的规范体系几乎涵盖了 "RESTful" API 的方方面面，成为了许多团队的敲门砖。一旦一个团队开始设计一个 API，他们就开始意识到 REST 给出的 guidance 少之又少。与其在大体 API 还没搭建好的时候就开始浪费时间在争论设计细节上，许多团队转而参考 JSON API 的指导性说明。

基本的 JSON API ( 英文，中文 )提供了下述规范：

表示单个来源 vs. 来源合集
定义来源，包括异质（混合类型）来源
将主要和相关来源包含在单一符合文档中
表示不同来源之间的关联
来源的超媒体链接、关联、分页合集等等
抓取、创建、更新和删除来源及关联
稀疏字段集（例如：限制每一个来源占用的字段）
来源排序
主要和相关来源分页
过滤来源
错误状态和数据

JSON API 网站也提供了一些基本规范之外的建议 ( 英文，中文 )：

成员命名
URL 设计
过滤策略
支持客户端缺省 PATCH

值得注意的是，基本规范和非常规建议和 HTML 语法是互补的，并不冲突。

一个活跃的生态环境

团队不仅能通过采用 JSON API 的规范节约大量时间，另一方面，搭建一个完全兼容的 API 还可以带来长远和广泛地利益。

JSON API 兼容多种语言和框架的库 ( 英文，中文 )环境正处在活跃的开发状态中。无论你是搭建一个客户端还是服务器，你都需要依赖于这样一个生态环境的帮助。确实很多工具都还处在发展阶段，这两年中 JSON API 自身也在经历不小的变化。不过随着格式规范进入稳定期，相信越来越多的工具会和 1.0 兼容起来。

从 0 到 1.0

从初稿到大纲到 spec

JSON API 起初的着眼点非常小。随着目标范围的扩大，spec 的一部分领域变得相当灵活，这使得各种可能性选项很难真正站稳脚跟（举例来说，URL vs. ID 样式，主要数据的键依据数据 vs. 依据来源类型）。

JSON API 逐渐演变成为开发 API 服务的一系列流动大纲，但是还称不上是一个 spec。

“大纲阶段”在 2014 年停留了许久。回过头来看，这一段时期称得上是无价之宝，因为开发者在期间尝试和发现了各种可用和不可用的方案。2014 年底，当 Yehuda 和我坐下来重新翻写 spec 的时候，我们得以从过来人的经验中挑选出最符合开发者需要的路径。我们把许多“ SHOULD ”改写成了“ MUST ”。这使得 spec 的 RC2 拟稿变得更有针对性，和今年 3 月发布的 1.0 版本也越来越接近了。

润色1.0

尽管当时面临着诱惑，然而幸好我们没有把 RC2 作为 JSON API 1.0 发布。我们决定给那些应用工具一个赶上节奏的机会，顺便也从整体上测试一下新的 spec。我们意识到已经有许多工具能和但仍然需要一些时间去彻底检验新规范的可靠性。

两个核心参与者， Tyler Kellen 和我积极地开发了一堆兼容库。Tyler 正和他在 Bocoup 的同事搭建 Node 终端。在 Cerebris， Larry 和我正在为 Rails 搞一个服务器工具， JSONAPI::Resources ，与此同时还有一个 JavaScript 客户端工具， Orbit.js 。在最终的 RC3 / RC4 阶段，我们都力图保证这些库和 spec 兼容，以确认任何改动的有效性。

在最后关头，真的是靠团队的力量走过来得。这里要特别感谢 Ethan Resnick, Kalle Tuure, hhware, Ward van Teijlingen, 和 Christoph Ziegenberg 的贡献。他们在最后几个月狂砸 pull resquests 发 issues，以确保 JSON API 1.0 足够坚挺并支撑到 1.0+之后。

我非常自豪，也非常感激 JSON API 团队能够在一起攻克掉无数历史遗留的疑难问题。是这一切让 1.0 最终诞生。

JSON API 1.0+

我很期待 JSON API 在它的生态环境步入成熟的时候能够发挥出全部的潜能。很快，能够与 1.0兼容的工具会支持最火的那些语言和框架。兼容性测试工具也会马上被开发出来，对这一点我很乐观。

另一方面，Ember Data 也比此前任何时候都更能接纳 JSON API了。 Ember Data 的 JSON API 适配器和序列器已几乎接近兼容水平。由于 JSON API 格式将作用于标准化数据的内部使用，这些架构层会变得相当精简。以上这些变化会在 Ember Data 1.0 中实现。

基于 spec 结构的可扩展性，1.0 之后的版本会朝着更有趣的方向发展（在不破坏原有规则的情况下）。

比如说，我希望随着链接概念的延伸，JSON API 能有更进一步的超媒体功能。

还有一点令人兴奋的是，我们还在探索扩展的各种可能性。虽然仍处在实验性阶段，扩展的部分应当允许客户端和服务器协议支持某些特定的功能，而这些并没有包含在基本 spec 里面。其中一个扩展的可能性就是能够允许在单个请求中进行 bulk 操作。

总之，JSON API 1.0 只是一个开始。能够参与这个项目我感到此生荣幸！