為 RESTful API 選擇數據類型

我們的工程團隊正在完善一個新的 RESTful API，您可以使用它來構建自己的應用程序并將 Phone.com 功能整合到您的業務系統中。

我們從未質疑過我們是否會使用 REST——幾乎可以肯定的是，REST 是構建 API 的最佳方式。幾乎一致認為 RESTful API 應該基于 JSON。但由于 REST 是一組體系結構指南，而不是協議或規范，我們必須在一開始就決定使用哪種媒體類型進行輸出。也就是說，我們將使用哪種 JSON 結構來傳達我們的數據。

沒有廣泛認同的 RESTful 數據結構方式，這導致我們對不少于六種不同的提議標準進行了冗長的分析！我們想分享一些關于我們的研究和我們所做的決定的信息。

我們在尋找什么

我們最初的目標非常簡單：

1. 避免從頭開發我們自己的格式。這個世界不需要另一種 JSON REST 媒體類型！
2. 選擇一種簡單易懂且易于開發者理解的類型，同時涵蓋我們的需求和用例。

我們發現了令人眼花繚亂的多種選擇：HAL，JSON-LD, 警報器，JSON API，Collection+JSON 和 Mason 都引起了我們的注意，雖然我沒有時間給出詳細的結構比較，但我確實想回顧一下每一個并提供我們的評論。

HAL（超文本應用語言）

所有 JSON REST 格式的鼻祖，HAL 于 2011 年首次提出. 這是一個輕量級規范，主要側重于 API 資源之間的鏈接。

我們喜歡 HAL 的簡單性。不幸的是，對于我們的目的而言，它太簡單了。HAL 不支持表單——僅支持鏈接——并且不支持錯誤處理等高級主題。然而，我們確實喜歡它如何提供嵌入式資源和具有相同關系的多個鏈接。

JSON-LD（關聯數據的 JSON）

這是另一種早期的輕量級格式。JSON-LD 主要用于將鏈接結構反向移植到現有的 JSON API 上。它的核心也不支持高級要求，盡管有一種名為 Hydra，它試圖解決這個弱點。

由于我們的 API 是全新的，因此我們不需要 JSON-LD 的主要用例，即改造現有的 JSON API。所以我們一直在尋找。

警報器

較新的 JSON 媒體類型是 Siren。雖然我們贊賞它對表單的處理，但 Siren 沒有錯誤處理并且對復雜的 POST 或 PUT 請求的支持不足。此外，我們發現它在 class 屬性中定義媒體子類型的概念很笨拙且不發達，我們不喜歡它更嚴格的數據結構，這需要將數據封裝在 properties 對象。

JSON API

沿著嚴格規范的趨勢走得最遠的是 JSON API。在我們考慮的所有媒體類型中，它的規格最長、最詳細。它甚至定義了必須返回哪些 HTTP 狀態代碼，以及必須如何處理輸入參數。對于那些愿意將幾乎所有界面設計決策都交給規范的人來說，沒有比這更好的了。

但是，Phone.com API 的需求在幾個方面都很復雜，我們不相信 JSON API 可以在不違反規范的情況下處理 100% 的需求——與規范有重大偏差的實現比完全沒有規格。

此外，我們認為 JSON API 將對象合并到其包含的數組中的方式可能適合那些希望嚴重依賴緩存數據的客戶，但它確實會使數據結構復雜化，并且很難看到其中的內容。雖然在客戶端應用程序完成后這不是問題，但 API 的可用性在編寫客戶端的過程中最相關，而不是之后。開發人員必須能夠快速輕松地理解其中的內容，以便首先編寫客戶端。

集合+JSON

我們發現 Collection+JSON（現已合并到名為 Collection.Dot+JSON）的變體非常適合大量使用列表的 API，這當然適用到 Phone.com API。我們也很感激它能處理我們的一些高級用例，而不僅僅是鏈接。然而，Collection+JSON 強加了一個嚴格的數據結構，要求一切被構造為一個列表，甚至是表示單個對象的 API 端點。

梅森

最后但絕非最不重要的一點是，我們探索了 Mason——具體來說，草案 2。雖然在 JSON REST API 社區中相對不為人知，但我們發現它是一個非常強大的選項，可以靈活地處理我們的各種用例。Mason 有錯誤處理和復雜表單支持的規范。它還包括 multipart/form-data 請求的規范，這對于 JSON 媒體類型來說很少見。

對于表單，除了模板化 URL 之外，Mason 還包括對 JSON-Schema 的明確支持，使其非常靈活。通過允許人類可讀的標題和描述，它也對開發人員更加友好，可以通過特殊的請求標頭在生產中將其關閉。

Draft 2 還結合了帶有鏈接和表單的創新理念。幾乎所有其他媒體類型都將表單和鏈接拆分到單獨的列表中，但 Mason 將它們組合到一個單獨的 @controls 屬性中。這導致更簡單的數據結構和更自然的分組，API 客戶端可能為給定資源提供的所有不同選項。

總的來說，我們發現 Mason 有很多值得喜歡的地方！我們發現的唯一真正的缺點是開發人員缺乏意識。它只存在了幾年。

確定 JSON 類型

在我們對每種媒體類型進行第一次審查后，我們開始欣賞那些關注高級用例的媒體類型，例如錯誤處理和表單。我們最初傾向于使用 Collection+JSON，但我們對數據結構剛性和非列表數據的笨拙處理的擔憂促使我們轉向其他地方。我們最終愛上了 Mason草案 2。我們認為它在穩健性和開發人員友好性之間取得了最佳平衡。

實施后

我們決定使用 Mason 數據類型已經三個月了。在此期間，我們編寫了三個不同的 Mason API，而不是一個，我們非常高興！

為了您的參考，我們開源了兩個 PHP 庫來幫助完成此類任務。請隨時檢查它們！

• Mason-PHP
• Mason-Laravel

我們很想聽聽您對為您的 API 項目選擇 JSON 數據類型的想法。是什么促使您選擇上述類型之一，或者我沒有提到的另一種數據類型？