JSON API 1.0 核心開發者自述 | 你所不知道的那些技術細節

時間 2019-12-05

標籤 json api 1.0 核心開發者自述所不知道那些技術細節欄目 JavaScript 简体版

原文原文鏈接

2013年5月，Yehuda Katz 完成了JSON API(英文，中文) 技術規範的初稿。事情就發生在 RailsConf 以後，在那次會議上他和 Steve Klabnik 就 JSON 雛形的技術細節相聊甚歡。在溝通單一 Rails 服務器庫—— ActiveModel::Serializers 和單一 JavaScript 客戶端庫—— Ember Data 的強烈呼聲下，JSON API 應運而生(關於這段歷史，我在2013年2月第一屆 EmberCamp 上有一個演講，感興趣的能夠去看一看)。git

打造任何客戶端和服務器庫都能運用的技術規範格式，Yehuda 和 Steve 在用戶的痛點中看到了這件事的價值所在。關鍵的一點是，這樣一種技術規範要能並行發展，而不是限制在最初的應用對象上。結果是，JSON API 同時受到了來自 Ember 和 Rails 圈裏圈外開發者的影響，並發展成爲可以迎合更大市場的強有力 spec。
通過兩年的醞釀、四輪備選發佈方案、Git 上數百個 pull request 和無數的爭議探討，JSON API 終於推出了 1.0 版本。github

在這個 JSON API 生命的關鍵點，有必要回顧一下它是如何走到 1.0，未來又該何去何從？首先，咱們來講說 JSON API 有什麼特別之處……json

雄心勃勃的 JSON API

JSON API 在目標和視野上頗具野心：它不只定義了一種媒體類型 (application/vnd.api+json) ，還制定了規則用 HTTP來抓取和修改此種媒體類型呈現的內容。從這個角度來講，JSON API 和 Collection + JSONspecification 有點像，但顯然它比後者的視線更廣。api

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)等等這些功能，使得客戶端可以從服務器那裏精確地請求得到他們須要的數據而沒有別的雜七雜八的東西。app

好比咱們來想象一個博客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 只是一個開始。可以參與這個項目我感到今生榮幸！