Google公開了雲服務API設計指南

Google公開了用于建立HTTP或RPC API的API設計指南。對于建立連接配接Google Cloud Endpoints的gRPC API的開發人員來說，這些設計原則更值得推薦使用。

早在2014年，Google在建立雲服務API或其它服務API時就開始在内部使用了這些設計指南。指南中探讨了HTTP或RPC API的設計。雖然HTTP API（也稱為REST API）的優點是公認的，但是它們距離實用尚有時日。Google推薦RPC尤其是其變體gRPC。據Google說，雖然大部分的網際網路API是HTTP，但是通常被雲服務和服務提供商内部使用的是RPC，并在數量上遠高于HTTP API。

對于通過方法操作一個或多個資源這樣的場景，Google推薦在設計RPC API時使用類REST方法。資源（也可稱為域實體）使用URI表示，也可以在網絡路徑格式後面加上唯一的名稱（ID）。同一類型的資源将組織成同一集合。

使用的标準方法包括Create、Delete、Get、List和Update。對于不能映射到任一标準方法上的操作，例如資料庫事務，使用者也可以建立自定義方法。推薦使用較少的方法來操作盡可能多的資源。

在建立資源時，推薦執行如下步驟：

确定API提供的資源類型。 确定資源間關系。 基于類型和關系确定資源的命名模式。 确定資源模式。 為資源附加最小的方法集。

Google使用“語義化版本”标準命名版本，命名使用三個數字，形式為“主版本.次版本.更新檔”。預釋出版本在命名時添加了一個字首，例如“1.0.0-alpha”。

對于資源、标準、自定義方法、标準域、錯誤、使用proto3建立API等方面，指南提供了更多細節和例子。

本文轉自d1net（轉載）