Google API 設計指南 - 前言

原文地址：https://cloud.google.com/apis...
Copyright: Creative Commons Attribution 3.0 License
Current Version of the API Design Guide: 2017-02-21
翻譯日期: 2月23日，2017

前言

這是一份適用於網絡API的通用指南。本指南自2014 年起在Google 內部使用，而且是咱們設計Cloud API 和其它Google API 時所遵循的依據。咱們將這份指南分享出來供外部的開發者參考，使咱們之間的共同開發變得輕鬆。

外部開發者可能會在設計配合Google Cloud Endpoints 使用的gRPC API 時以爲本指南尤爲有用, 且咱們強烈推薦此類開發者聽從這些設計原則。不過咱們並不強求任何非谷歌的開發者遵循本原則而且你徹底能夠在不參照本指南的前提下使用Cloud Endpoints 和/或gRPC 。

本指南對REST API 和RPC API 均爲適用，並對gRPC API 有特別的關注。gPRC API 使用Protocol Buffers去定義API 表層和API Service Configuration去配置其API 服務，包括HTTP 映射，日誌和監控。Google API 和gRPC Cloud Endpoints 使用HTTP 映射功能進行JSON/HTTP 到Protocol Buffers/RPC的轉碼。

本指南是一份不斷變化的文檔，不斷被採用、接納的新風格和設計模式會不斷地被添加進來。在這種指導精神下，本指南不會終結且在追尋API 設計的藝術及匠心上將一直都會有進步空間。

文檔用語

不一樣級別的要求類詞語:

• 絕對要求："MUST", "REQUIRED", "SHALL"

• 絕對不要："MUST NOT", "SHALL NOT"

• 通常應該："SHOULD", "RECOMMENDED"

• 通常不要："SHOULD NOT"

• 可能，可選 "MAY", "OPTIONAL"

在本文中使用解釋參照其在RFC 2119中的描述。
在本文檔中，這些關鍵詞由粗體高亮標示。

參考資料

• https://www.ibm.com/developer...

• http://www.ruanyifeng.com/blo...