Google API 設計指南 - 面向資源的設計
引言
2010年的時候，就研究過REST，那個時候還不是很理解REST。那個時候也在理解SOA，也是很火的概念，可惜我一直專注在系統架構的內部，也終究未能完好消化下去。最近重新在思考URI、API設計相關的問題，去學習Google API設計指南--面向資源的設計的時候，又想起來了。希望下次思考的時候應該就可以收放自如地把系統內部的介面可以很理想地開放出去，通過REST或者通過SOA。有一些東西是很適合通過REST開放的，有一些通過SOA開放可能更適合一點。下面這篇文章可以看作是REST架構的一個實踐。
文章轉載自Google API 設計指南 - 面向資源的設計
這篇設計指南的目的是幫助開發者設計出
傳統上，人們參考像 CORBA 和 Windows COM 這樣的 API 介面和方法來設計 RPC API。隨著時間推移，越來越多的介面和方法被新增。最後的結果是被數量眾多的介面和方法淹沒，每一個都和其他不同。為了正確使用它們開發者必須仔細學習每一個介面或方法，這必定會消耗時間並容易引入問題。
REST 架構風格最早出現於2000年，主要設計為與 HTTP/1.1 一起使用。它的主要原則是定義能夠被少量方法操作的命名資源。資源和方法被認為是 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 設計中，並且定義了許多通用的設計模式來提升可用性並降低複雜性。
注意：此設計指南解釋瞭如何在獨立於程式語言、作業系統或者網路協議的 API 設計中應用 REST 原則，而不是僅用於建立 REST API 的指南
什麼是 REST API？
REST API 被建模成可單獨定址的資源（API 的名詞）的集合。資源通過它們的資源名來引用，通過一小組方法（也被稱為動詞）來操作。
REST Google API 的標準方法（也叫 REST 方法）是 List Get Create Update 和 Delete。當存在類似資料庫事務這種不能被簡單地對映到標準方法的需求時，API 設計者也可以使用自定義方法（也叫自定義動詞或自定義操作）。
注意：自定義動詞不表示創造自定義的 HTTP 動詞來支援自定義方法。對於基於 HTTP 的API，簡單地對映到最合適的 HTTP 動詞即可。
設計流程
此設計指南建議採用如下步驟來設計面向資源的 API（更詳細的內容請參考後面的小節）
-
確定 API 提供的資源型別
-
確定資源間的關係
-
依據型別和關係來確定資源名方案
-
確定資源結構
-
為資源新增最少的方法集
資源
面向資源的 API 通常以資源層次進行建模，每一個節點是一個簡單的資源或資源集合。方便起見，通常將它們稱為資源和集合。
-
集合包含具有相同型別的資源列表。例如一個使用者擁有聯絡人的集合
-
資源擁有一些狀態和 0 個或多個子資源。每一個子資源可以是簡單資源或資源集合
例如，Gmail API 有使用者的集合，每個使用者有資訊的集合、執行緒的集合、標籤的集合、一個資料資源和一些設定項資源。
雖然儲存系統和 REST API 之間存在一些概念上的一致性，但是具有面向資源的 API 的服務不一定是資料庫，並且在解釋資源和方法方面具有巨大的靈活性。例如，建立日曆事件（資源）可以為參加會議者建立附加事件，向參加者傳送郵件邀請，預約會議室和更新視訊會議時間表。
方法
面向資源的 API 的關鍵特性是它通過對資源執行的方法（功能）來強調資源（資料模型）。一個典型的面向資源的 API 通過少量方法暴露大量資源。這些方法可以是標準方法也可以是自定義方法。對於本指南，標準方法是 List Get Create Update 和 Delete。
當一個 API 功能自然地對映到一個標準方法時，應該（should） 在API 設計中使用此方法。對於不能自然對映到標準方法的功能，可以(may) 使用自定義方法。自定義方法提供了與傳統 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 服務實現了Google Cloud Pub/Sub API，它定義了下面的資源模型：
-
API 服務：
pubsub.googleapis.com -
話題集合：
projects/*/topics/* -
訂閱集合：
projects/*/subscriptions/*
注意：其他 Pub/Sub API 的實現可能會選擇不同的資源名稱方案
Cloud Spanner API
The spanner.googleapis.com service implements the Cloud Spanner API, which defines the following resource model:
- API service:
spanner.googleapis.com - A collection of instances:
projects//instances/.- A collection of instance operations:
projects/*/instances/*/operations/*. - A collection of databases:
projects/*/instances/*/databases/*. - A collection of database operations:
projects/*/instances/*/databases/*/operations/*. - A collection of database sessions:
projects/*/instances/*/databases/*/sessions/*.
- A collection of instance operations: