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 只是 一個開始。可以參與這個項目我感到今生榮幸！

文章來自：http://1ke.co/course/346