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...