Google API 設計指南 - 面向資源的設計

• 原文地址: https://cloud.google.com/apis...

• 當前版本: 2017-02-21

• 翻譯日期: 2月24日，2017

• Copyright: Creative Commons Attribution 3.0 License

面向資源的設計

本指南的目標是幫助開發者設計出簡介、一致且好用的網絡API 。與此同時，此指南也有助於統一基於socket 的RPC API和基於HTTP 的REST API 的設計。

長久以來，人們經過API接口和方法，如CORBA 和Windows COM 來設計RPC API。隨着時間流逝，愈來愈多的接口和方法被引入。最終的結果將是數目驚人且各不相同的接口和方法。爲了正確的使用它們，開發者不得不得進行仔細的學習，這不只耗時並且易錯。

REST風格體系最先在2000年被提出，並被設計爲配合HTTP/1.1工做。REST的核心原則是定義可被少量方法進行操做的命名資源。這些資源和方法被稱爲API 的名詞 (nouns) 和動詞 (verb)。在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 是一系列個體可描述 (individually-addressable) 的資源（API的名詞）的模型。資源能夠經過他們的資源名稱來說起，並能夠經過一個小集合內的方法（即API的動詞）來操做。

REST Google API 的標準方法（也被稱爲REST方法）包括List, Get, Create Update 和Delete。當功能不能輕鬆地映射到標準方法時，如數據庫事務，API設計者也可使用自定義方法（也被稱爲自定義動詞或自定義操做）。

注意： 自定義動詞並不意味着建立自定義HTTP動詞來實現自定義方法。對於基於HTTP的API，自定義動詞會被映射到合適的HTTP動詞上。

設計流程

The Style Guide suggests taking the following steps when designing resource- oriented APIs (more details are covered in specific sections below):

本指南建議按照下列步驟來設計面向資源的API（更多細節會在之後具體的章節所描述）。

• 肯定API提供的資源類型

• 查明不一樣資源間的關係

• 根據資源的類型和關係，決定資源名稱的規範

• 決定資源的範式 (schema)

• 爲資源加上方法的最小集合

資源 (Resources)

面向資源的API一般按照資源階層進行建模，其中每個節點能夠是單個簡單資源或者是一個資源集合。爲了方便，他們一般被分別稱爲一個資源或者一個集合。

一個集合含有一系列相同類型的資源。好比，一個用戶擁有一個聯繫人集合。一個資源擁有一些狀態以及0個或多個子資源 (sub-resource)。每一個子資源能夠是簡單資源或者是資源集合。舉例來講，Gmail API 有一個用戶資源集合，其中每一個用戶擁有消息集合，帖子集合，標籤集合，一個用戶資料資源和若干個用戶設置資源。

儘管在存儲系統和REST API 之間有一些概念上的一致性，但提供面向資源的API 的服務卻不必定要是一個數據庫，而且其在解釋資源資源和方法時用於很大的靈活性。例如，建立一個日曆時間（資源）可能會爲與會者建立額外的時間，發送郵件邀請給與會者，預約會議室並更新視頻會議日程。

方法（Methods)

面向資源的API 的關鍵特色是它強調資源（數據模型）甚於做用於資源的方法（功能性）。一個典型的面向資源的API 會暴露大量的僅具備少數方法的資源。方法能夠是標準方法，也能夠是自定義方法。對於本指南，標準方法是：List, Get, Greate, 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 服務實現了Google Cloud Pub/Sub API, 其定義了下列資源模型：

• API服務: pubsub.googleapis.com

• 主題資源集合: projects/*/topics/*

• 訂閱資源集合: projects/*/subscriptions/*

注意： 其它Pub/Sub API 實現可能採用不一樣的資源名稱範式