Google API Design Guide (谷歌API設計指南)中文版

面向資源的設計

這份設計指南的目標是幫助開發人員設計簡單、一致、易用的網絡API。同時，它也有助於收斂基於socket的API和（注：原文是with，這裏翻譯爲「和」）基於HTTP的REST API。

之前，人們根據諸如CORBA和Windows COM這樣的API接口和方法設計RPC API。隨着時間的推移，接口和方法愈來愈多。最後，接口和方法數不勝數又各不相同。開發人員要正確使用它們，必須仔細瞭解每個的用法，這很浪費時間並且容易出錯。

2000年，爲了與HTTP1.1搭配使用，REST架構風格出現。它的核心原則是定義用少許方法就能操做的命名資源。資源和方法可視爲API的名詞和動詞。在HTTP協議中，資源名稱天然地對應於URL，方法則對應於HTTP的POST、GET、PUT、PATCH和DELETE方法。

在互聯網領域，HTTP REST API最近得到了巨大的成功。截至2010年，大約74%的公網API都是HTTP REST API。

儘管HTTP REST API在互聯網領域已經很流行了，但其承載的流量仍是比傳統的RPC API小。好比，在高峯期，美國大約一半的互聯網流量都是視頻內容，出於性能上的考慮，不多有人用REST API。在數據中心內部，更多的公司也使用基於socket的RPC API來承載大多數網絡流量，這比REST API的數量高出幾個量級。

事實上，RPC API和HTTP REST API都有存在的理由。在理想狀況下，API平臺最好提供這兩種API。這份設計指南也是基於這一原則幫你設計和構建API。在通用API設計上，本指南應用面向資源設計的原則，定義了衆多常見的設計模式以提升易用性並下降複雜性。

注意：本設計指南解釋瞭如何將REST原則用於獨立於編程語言，操做系統或者網絡協議的API設計，它不僅是用於建立REST API的指南。

什麼是REST API

一組REST API被建模爲一組可獨立尋址的資源（API的名詞）。資源被經過資源名稱被引用，經過一小組方法（也被稱爲動詞或者操做）被操做。

Google REST API（也被稱爲REST方法）的標準方法有List，Get，Create，Update和Delete。API的設計者也能夠用自定義方法（也被稱爲自定義動詞或者自定義操做），來完成那些不易對應到標準方法的功能，好比數據庫事務。

注意：自定義動詞不意味着建立自定義的HTTP動詞以支持自定義方法。對於基於HTTP的API來講，自定義動詞被對應到最合適的HTTP動詞上。（譯者注：不能自創HTTP動詞，應該使用含義最接近的HTTP動詞去設計API）

設計流程

設計指南建議使用如下步驟設計面向資源的API（更多細節請參考下面指定章節）：

• 肯定一個API提供什麼類型的資源
• 肯定資源之間的關係
• 根據資源類型和關係肯定資源命名方案
• 明確資源schema
• 給資源添加最少的方法集

資源

面向資源的API一般被建模爲一個資源層次結構。其中每個節點能夠是一個簡單資源也能夠是一組資源。爲了方便，它們一般被稱爲資源或者資源組。

• 資源組包含相同類型的一系列資源。好比，一個用戶有一組聯繫人。
• 資源有相同的狀態，也有零或者多個子資源。每個子資源能夠是單個資源也但是一組資源。

例如，Gmail API有一組用戶，每一個用戶有一組消息，一組主題，一組標籤，單個用戶配置資源或多個設置項資源。

儘管REST API和存儲系統有概念上的一致性，但具備面向資源的API的服務不必定是數據庫，而且在如何解釋資源和方法上有巨大的靈活性。好比，建立一個日曆事件（資源）可能會爲參會者建立附加事件，向參會者發送邀請郵件，預定會議室，更新視頻會議日程表。

方法

面向資源的API的關鍵特性是強調資源（數據模型）和（譯者注：原文看起來是筆誤，這裏應該翻譯爲和）運行在資源上的方法（功能）。典型的面向資源的API經過少許方法的暴露大量資源。這些方法能夠是標準的或者自定義的。在本指南中，標準方法是指：List,Get,Create,Update和Delete。

當API功能天然地映射到一個標準方法時，這個方法應當用於API設計。若當功能不能天然的映射到標準方法時，能夠使用自定義方法。自定義方法能提供與傳統RPC API同樣的設計自由度，能夠用來實現常見的編程模式，好比數據庫事務或者數據分析。

例子

接下來，咱們看一看現實中如何使用面向資源的API來設計大規模服務。

Gmail API

Gmail API服務實現了Gmail API，暴露了絕大多數Gmail的功能。它的資源模型以下：

• Gmail API服務：gmail.googleapis.com
• 一組用戶：users/*。每一個用戶有以下資源。
  • 一組消息：users/*/messages/*。
  • 一組主題：users/*/threads/*。
  • 一組標籤：users/*/labels/*。
  • 一組變動歷史：users/*/history/*。
  • 一個表明用戶資料的資源：users/*/profile
  • 一個表明用戶配置的資源：users/*/settings

Google Cloud Pub/Sub API

pubsub.googleapis.com服務實現了Goole Cloud Pub/Sub API，它定義瞭如下資源模型：

• API服務：pubsub.googleapis.com
• 一組主題：projects/*/topics/*。
• 一組訂閱：projects/*/subscriptions/*。

注意：PUB/SUB API的其餘實現可能選用了與上面不一樣的命名規則。

來源：https://www.bookstack.cn/read/API-design-guide/API-design-guide-02-%E9%9D%A2%E5%90%91%E8%B5%84%E6%BA%90%E7%9A%84%E8%AE%BE%E8%AE%A1.md