Google Cloud的API 設計,google cloud

Google Cloud的API 設計

最近（很久前）在設計API接口的時候發現了一些很難取舍的地方，就看了下業界領先的企業都是怎么設計類似API的，發現了很多之前設計的缺陷和一些新的思路。主要參考了AWS和Google Cloud的API設計，兩家的設計可以說是把兩個不同的風格發揮到了極致，做同樣的事情API的各個方面都可以設計的完全不一樣。Google有一個自己的API Design規范可以在網上找到，不過真實的GCE API規范略有一些出入。而AWS的API設計是沒有什么文檔的，只能通過現有的API進行逆向工程來反推設計理念。這篇文章會比較瑣碎，更像是一個讀書筆記，細節的東西會比較多。

Google Cloud API

由于Google的文檔比較詳細了，就先照著Google的文檔來講，而Google的API是按照REST風格來的，而REST只是一種紙面的模式，每家的實現可能都不一樣，我們就來看下Google眼里的REST是什么樣的。然后介紹一下REST API的一些局限和缺點以及Google的解決方式。

最權威的REST當然還是得去看論文了，不過對于普通開發者來講HTTP的REST就是一個URL指向一個資源，然后這個URL上通過不同的HTTP方法來實現對這個資源的不同操作。簡單來說就是指向資源的URL+HTTP方法就構成了常見的REST API。這里面每一個部分都有很多門道。

URL

URL可以分成好幾個組成部分

1.域名，不同的域名可以區分這個網站提供的不同API服務。比如一個圖書，一個電影，域名就應該是https://library.oilbeater.cn和https://moive.oilbeater.cn

2.版本號，對應不同的歷史版本，可以是v1,v2,也可以是alpha,beta這樣

3.資源集合，書店里可能會有多種資源的集合，比如圖書，報紙，影碟，這就需要用資源集合來區分/books,/newspapers,/cds等等

4.資源名稱，這時候才真正到具體的資源，一個圖書可能就是https://library.oilbeater.com/v1/books/book1

5.子資源,有時候一層的資源模型不能滿足現實的需求，比如圖書館的檢索是按照書架來的，需要先知道在哪個書架才能找到書，就需要在中間插一層資源。最后的url可能就變成了https://library.oilbeater.com/v1/shelves/shelf1/books/book1

6.重復34

資源命名

1.資源名必須是合法的C語言變量名，這個規范主要是為了代碼和SDK的一致性，不然有個減號這樣的字符很多語言的SDK里這個資源對象你就不得不換個名字或者寫法了，很容易造成不一致，一些自動生成SDK的工具也會失敗

2.資源集合必須是復數

3.不要用縮寫避免不必要的歧義

4.不要用過于泛化的資源類型，像type，object，element，resource這樣的命名一來不是很清楚，二來很容易和編程語言的關鍵字撞名字，人為增加編程難度。方法

常用的HTTP方法有GET,POST,PUT,DELETE稍微常見的還有HEAD,PATCH,不太常見的還有COPY，LINK，LOCK，VIEW等等。由于HTTP是純文本的協議，并沒有規定只能用哪幾個方法，只要服務端做處理就可以自己再自定義其他方法的，比如Google自己就實現了一個BATCH來做批量處理。

每個HTTP方法和以對應不同的語義，而且這些語義像GET是獲取，POST創建PUT更新DELETE刪除基本上大家都是形成共識的，API最后的統一性會很好。REST的初衷也是讓資源盡可能的多，每個資源的方法盡可能的只有標準的幾個方法，這樣所有的API看起來長得都很像，學習和實現的成本都會很低。下面說一下具體的每個方法需要注意的一些事情

List

1.需要用GET方法url指向資源集合，并返回資源的列表

2.List返回的內容最好有分頁信息，而不是簡單的一個資源列表，便于前端的展示并減少每次拿所有數據的性能消耗

3.資源列表需要是有序的，如果兩次請求同樣資源順序完全不一樣前端再不處理就會有奇奇怪怪的現象

4.List需要提供簡單的按照某個字段排序，filter方法，更復雜的過濾查詢需要單獨的方法

5.可以返回一些metadata，比如資源數量，資源集合的信息等

Create

1.POST方法URL指向資源集合，創建成功需要返回這個資源，而不是只有一個201的狀態碼

2.需要允許client自己指定resourceid，而不是全部由系統自動生成。這樣第三方系統可以根據情況進行重試和重復檢查。不然一個create請求中間路徑上有重試就會生成多個id不同的資源，后續處理會很麻煩。

Update

1.PUT或者PATCH方法URL指向具體資源，更新成功需要返回資源實體

2.PUT一般用于整個資源實體的更新，而PATCH只更新某個字段。對于一個復雜的有大量字段的資源，最好兩種API都提供，而不是只提供一個PUT。只提供一個PUT即使只更新一個字段也需要傳遞完整的資源實體，很多情況下是沒必要的

用戶自定義方法

由于HTTP的標準方法是有限的，而很多語義是標準方法不能表示的，比如需要把書從一個書架移動到另一個書架就很難用標準方法表示，這就需要用戶自定義方法。定義HTTP方法理論上沒問題，但很多第三方庫并不支持這種方法，這種API給別人看也會比較奇怪，所以通常會把方法加在url里，通常是加在資源名稱后面。比如移動一本書就可以是/books/book1:move

1.通常的做法是用『/』來做URL的分隔，但是在Google的規范里用的是用『:』因為/分隔會有歧義，不知道后面的到底是一個子資源還是一個用戶自定義方法。聽起來很有道理的樣子，但是在GCE的API里并沒這么做也是用的『/』

2.盡管URL里有了自定義方法，HTTP方法還是盡量用符合語義的，比如更新類的操作都用PUT

3.現實中很多操作都是標準HTTP方法表示起來很苦難的，比如重啟機器，發快遞郵件，賬號登錄這些，可以想一下這些操作如何用HTTP標準方法來設計API

標準字段

不同的資源有許多共同的屬性字段，由于每個資源對應的API可能是由不同人在不同時間完成的，所以需要有個約定好的公共字段的命名，不然到最后會出現混亂的情況。比如資源需要有個id表示，就會出現不同資源有的叫uuid，有的叫id，有的叫resourceid；創建時間又有createdat，createddatetime，createdtime，分頁又有pagetoken,nextpage,pagenum諸如此類不一致的情況。同樣一些字段的類型也需要統一，比如時間使用時間戳還是標準時間，帶不帶時區。

除了正常的返回就是錯誤返回也要有統一的格式。錯誤信息需要包含errorcode,errormessage和errordetail。其中errormessage是用來返回給最終用戶的，而errordetail則用于內部人源進行錯誤排查。

REST的缺陷

盡管REST API的設計原則在現實中使用的很廣，但是這種設計也是有很多局限性的。

1.層級設計很容易過多，比如在公有IAAS中需要獲得一privateip的信息，這個ip可能是屬于某塊網卡的，網卡屬于某個機器，機器屬于某個subnet，subnet屬于某個vpc，vpc屬于某個region。設計出來的api就變成了/regions/regionid/vpcs/vpcid/subnets/subnetid/instances/instanceid/nics/nicsid/privateips/privateipid這種API直接上就會覺得不合理。而且仔細考慮機器是不是應該屬于subnet，privateip是不是應該直接是subnet的子資源，會有很多需要考慮的地方。

2.標準HTTP方法大多是操縱整個資源，而這個粒度在一些情況下太粗了。比如同樣是更新一個主機的操作，更新主機的一個tag和更新主機的name都是PUT一個資源實例url，而更改安全組將主機狀態設置成停止也是同樣的PUT方法和url就會有些不合理。盡管都是更新操作，但是更新的字段不同，功能不同，重要性也不同，用同樣的大PUT就會不合適。而且這些字段可能會對應著不同的權限操作，如果任何更新都是同樣的方法，之后細粒度的權限控制也會變得十分痛苦。

3.涉及多資源的操作會很難設計。REST的思想是對資源進行操作，但現實中一個操作可能會對應多個資源，這時候對于多個不同資源關系的操作REST設計起來就比較頭疼了。比如給一個主機加一個eip，那么這個操作肯定要用到自定義方法了，接下來的問題就是這個方法到底是屬于主機的，還是屬于eip的還是兩個資源都需要加一個同樣的方法？而且API的設計也會影響實現的思路，在設計時API是把主機和eip當成獨立的資源，那么實現的時候很可能就忽略了他們倆之間是有關聯關系的，很可能到最后就會出問題。

4.批量操作變得困難。由于REST API的更新和刪除url路徑都是指向具體一個資源的，批量的更新刪除就需要額外進行設計。比如批量關閉幾個主機，API的樣子就會和其他的完全不一樣。如果不設計批量操作的API只是組合使用單個資源的API，當需要操作的實例多的時候很容易出現性能問題，而且如果操作時間過長，那么中間各種沖突，不一致的幾率就會大幅上升。

Google的應對方案

1.層級多的問題，翻一下google cloud的api可以發現大部分的api url只有三層，前兩層還都是project和zone，一個實例的url就是/v1/projects/project/zones/zone/instances/instance換句話說就是真正到了云里面的資源就沒有再分層了，所有的資源層級都是扁平的在同等地位，所有的資源都是關聯關系而不是層級關系。這樣就避免了層級過深和考慮如何設計層級的問題，也保證了將來每個資源操作的靈活性。

2.大量的自定義方法。盡管REST本來的目的是大量的資源少量的標準操作，很顯然這個顯示環境中是有困難的。Google在instance這個資源的自定義方法就有20多種，最后的情況就是大量的資源加上幾個標準方法再加上大量的自定義方法。通過自定義方法，每個方法對應一個操作，權限控制也可以對應到每一個方法上，細粒度的權限控制也就可以實現。

3.HTTP BATCH方法。至于批量操作的問題Google是通過自定義HTTP方法實現的，之前說過了不要用自定義HTTP方法因為大家不支持，可是Google這種能對Web標準起到影響的企業就任性了。BATCH方法其實就是在HTTP的body里再封裝多個標準的HTTP方法求情。這樣批量操作還是一個個的操作，不過可以一次性打包發過去不用一個個發快遞了。API也不用單獨再設計一套批量的，還能組合不同類型的操作，不過一般企業就不要學這種作風了。

盡管Google很詳細的做了API設計的文檔，但是如果你去看國內IaaS廠商的API文檔會發現沒有一家是這么做的，甚至連一點REST的模樣都沒有。Google的API設計看上去最符合開發者的常規思維，在這個領域反而顯得和一個另類一樣，為啥子呢？如果你看過AWS的API就會發現國內這些廠商大概都是從AWS那邊借（chao）鑒（xi）過來的。至于AWS是如何應對REST世界中的類似問題以及他到底長什么樣子，可能下篇會寫。

特別聲明：以上文章內容僅代表作者本人觀點，不代表ESG跨境電商觀點或立場。如有關于作品內容、版權或其它問題請于作品發表后的30日內與ESG跨境電商聯系。