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 还可以带来长远和广泛地利益。