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 只是 一个开始。可以参与这个项目我感到今生荣幸！

补充

若是你对学习 JSON API 感兴趣，请查看 jsonapi.org， jsonapi.org.cn。
若是你有任何的问题和建议，欢迎到 JSON API's Github 上来 repo！

文章来源：http://1ke.co/course/346