【API 架構】使用 JSON API 的好處

在 API 工藝的世界裏，沒有比設計更受熱議的領域了。從 REST、gRPC 到 GraphQL，有許多方法可以設計和標準化 Web API 交互。今天，我們將注意力轉向另一種方法，JSON API，JSONAPI.org 上詳細介紹的用於構建 API 的規範。

JSONAPI.org 中描述的 JSON API 非常適合使您的 JSON 響應格式更加一致。以提高生產力和效率爲目標，JSON API 因其可以消除多餘的服務器請求的高效緩存功能而受到吹捧。

在這篇文章中，我們將定義 JSON API 是什麼，並瞭解如何使用它來構建高效的 API。我們將介紹 JSON API 的一些主要優點，並通過 FitBit 的案例研究瞭解該規範在實踐中的應用情況。希望本概述將介紹 JSON API 的新手，並幫助您判斷它是否適合您的 API 場景。

什麼是 JSON API (JSONAPI.org)？

JSON API 是一種適用於 HTTP 的格式。它描述了客戶端應如何從服務器請求或編輯數據，以及服務器應如何響應所述請求。該規範的一個主要目標（現在是穩定的 v1.0）是優化 HTTP 請求；在請求數量和客戶端和服務器之間交換的數據包大小方面。

“JSON API 是一種有線 (Wire) 協議，用於通過 HTTP 增量獲取和更新圖形”
——耶胡達 · 卡茨

在 JSON API 中，客戶端和服務器都在請求文檔中發送 JSON API 數據，帶有以下標頭，而不指定媒體類型參數：

Content-Type: application/vnd.api+json

JSON API 表示如何調用資源以及如何共享相關鏈接。JSON 對象位於請求的根部，它必須包含資源數據、錯誤或元信息。數據以及與數據的關係可以通過 GET 調用來獲取，如下所示：

GET /articles HTTP/1.1
Accept: application/vnd.api+json

以下是資源類型 articles 在 JSON API 響應中的顯示方式：

// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}
// ...

到目前爲止，相當標準的東西。JSON API 支持創建、更新和刪除資源的典型 CRUD 流程。JSON API 將始終向後兼容，它是一個社區驅動的計劃，在 Github 上接受拉取請求。

使用 JSON API 的好處

既然我們對 JSON API 是什麼有了基本的瞭解，那麼有哪些獨特的優勢使它脫穎而出？

複合文檔

複合文檔是 JSON API 中的一項獨特功能，允許服務器將相關資源與請求的主要資源一起發送——如果實施得當，這可以減少必要的 HTTP 請求的數量。複合文檔使用 include 參數工作，如下所示：

GET https://api.example.com/posts?include=author

這使您能夠在初始請求中包含其他資源。

稀疏字段集

如果您使用複合文檔來包含相關資源，您可能會遇到回覆量大的問題。再一次，JSON API 有一個解決方案。

JSON API 的另一個獨特方面是稀疏字段集，它使客戶端只能從特定字段請求數據。它通過將要檢索的字段添加到具有資源名稱和所需字段的 URI 參數來工作。這提供了額外的定製，可以減少臃腫。它看起來像：

GET /articles?include=author&;fields[articles]=title,body&;fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

稀疏字段集是一種標準化方法，它允許客戶端僅指定他們希望從對象中包含在響應中的屬性。使用稀疏字段集，您只能獲得所需的字段，提供獨特的定製潛力，這對精益數據共享環境很有吸引力。

可選性

JSONAPI.org 中的許多功能都是可選的；您可以關閉或打開它們。這些功能使客戶能夠決定接受哪些資源，從而很好地適應精益的移動環境。讓客戶就如何檢索和處理數據達成一致是有幫助的，因爲它消除了冗餘和優化以減少膨脹。

優化功能

JSON API 配備了許多功能來優化 API 返回包。JSON API 中的特殊服務器端操作包括排序和分頁；將返回資源的數量限制爲子集的能力，包括 first、last、next 和 prev 鏈接。

緩存

在他的演講中，Lee 強調了定義良好的資源如何提高緩存能力，從而提高最終用戶的 “感知速度”。

“因爲數據變化影響的資源更少，所以數據變化時失效的資源更少”

在 JSON API 用例中，緩存本質上是內置在 HTTP 中的。由於使用 JSON API 的客戶端以相同的方式訪問數據，因此他們不需要將數據存儲在不同的位置。這種設計可能需要轉變思想，但如果使用得當，可以帶來顯着的優化優勢。

JSON API 如何在實踐中使用：FitBit 案例研究

讓我們看看 JSON API 如何在實踐中實現以設計高效的 API，使用 FitBit 作爲現實生活中的案例研究。

Jeremiah Lee 在 FitBit 領導 API 開發 4 年，在此期間他參與了他們的 JSON API 採用。健身可穿戴公司 FitBit 擁有蓬勃發展的 API 程序；在每年 40 億次請求中，有 1/4 是通過第三方應用程序完成的，收入可觀。

符合 API 風格有助於標準化客戶端

一個常見的問題是當不同的客戶端類型偏好不同的方法來從服務器檢索數據時。圍繞功能區域形成的工程團隊通常一次一個平臺地逐步實施新功能，並在每個客戶端中找到相反的約束。

Lee 描述了 FitBit 團隊如何擁有四個主要客戶：Android、iOS、Windows 和 Web。一個主要問題是 Android 和 iOS 對 API 應該如何運行有非常不同的想法。iOS 更喜歡較少的網絡請求和較大的 API 響應，而 Android 更喜歡更多的網絡請求和較小的 API 響應。

爲了將這些約束規範化爲一致的數據模型，團隊必須首先解決請求數量和請求大小之間的爭論。FitBit 團隊在具有敵對數據網絡的移動環境中工作，無法依賴理想的客戶端連接。

相信 HTTP/2、TLS 1.3 和改進的 LTE 網絡的日益普及，FitBit 團隊決定他們可以減少請求的開銷、發出併發請求並減少安全延遲問題，同時相信更多彈性連接。這將導致他們採用更小的資源和許多輕量級的 HTTP 請求。

JSON API 幫助創建一致的數據模型

“如果沒有明確的指導，數據模型可能會變得混亂。”
——耶利米 · 李

Lee 描述了在 FitBit，他們的 API 如何開始類似於 “視圖模型”；現有端點變得超載，數據相關性鬆散，而不是範圍廣泛。團隊正在根據用戶體驗視圖重載端點。

隨着客戶體驗隨着時間的推移而發展，團隊正在以任意方式拆分數據。由於沒有權威或風格可以遵循，這造成了很多不一致。客戶端和服務器數據模型之間的錯位造成了問題。團隊需要就如何檢索數據和處理數據達成一致，並且需要能夠以很少的開銷檢查數據更改。

他們傾向於使用 JSON API 來規範化他們的數據。使用 JSON API 定義數據之間關係的能力，他們能夠建立客戶端 - 服務器通信期望。

JSON API 有助於保持同步

FitBit 案例中的另一個問題是與服務器保持同步。他們的設備需要經常與服務器同步，並且這些數據也可以被第三方應用程序修改。

這些更改必須非常快速地反映在所有 API 客戶端中。JSON API 利用的 HTTP 緩存使他們能夠防止召回過時的數據，從而減少冗餘並提高最終用戶的感知速度。根據 Lee 的說法，這真的開始在一個應用程序中疊加多種體驗。

比較 JSON API 和 GraphQL

既然我們本質上是在討論使用圖形，爲什麼不使用 GraphQL 呢？雖然您可以使用 GraphQL 實現許多相同的功能，但 Lee 看到了採用 JSON API 的兩個主要好處：分頁和可緩存性。

分頁是 GraphQL 沒有專門解決的一個領域。或者，當客戶端請求它們時，JSON API 會向客戶端提供諸如 next 和 prev 之類的鏈接。由於 GraphQL 中的分頁完全由客戶端處理，Lee 認爲這很不幸，因爲客戶端可能會在不知不覺中進行昂貴、耗時的數據庫查詢。

GraphQL 也沒有利用 HTTP 緩存功能，因爲它與協議無關。由於沒有建議的通用方法，這意味着每個 GraphQL API 處理緩存的方式都會略有不同。

“我個人認爲緩存對於客戶端性能考慮來說太重要了，不能事後考慮”
——耶利米 · 李

Lee 還指出，使用 JSON API 意味着開發人員不必採用像 GraphQL 這樣的另一個工具鏈，而是可以繼續使用他們很可能已經熟悉的技術。

GraphQL 的許多好處，例如查詢效率和減少往返調用，都可以在 JSON API 中使用稀疏字段集和複合文檔進行匹配。JSON API 因此可以提供與 GraphQL 相同的功能。

考慮將 JSON API 用於 “實用” 的 API 設計

JSON API LogoJeremiah Lee 稱其爲 “務實”，我們必須同意。如上所述，讓客戶端和服務器共享一個通用數據模型（如 JSON API）有很多優點。

“JSONAPI.org 規範應該是您的智能默認設置”
——耶利米 · 李

雖然 JSON API 並不適合所有情況，但許多人聲稱它是客戶端和服務器通過 HTTP 共享通用數據接口的一種很好的默認方式。憑藉上面列出的優勢，以及它的健康採用，JSON API 似乎是 API 風格的有力競爭者。

我們鼓勵您自己閱讀規範。您如何看待 JSONAPI.org？您使用什麼規範來定義您的 API 和數據模型？

超級架構師 架構師的寶庫，每天一篇，開拓你的視野和深度。分享企業架構，業務架構，應用架構，數據架構，技術架構，安全架構等。討論架構框架, 規劃，治理, 標準，落地。交流新興的架構風格和模型。如微服務，事件驅動，微前端，大數據，數倉，物聯網，人工智能架構。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/DIQQ7R1TyBEU7rnjwb5eSw

猜你喜歡