google api设计指南-简介

简介

这是联网 API 的通用设计指南。它自 2014 年起在 Google 内部使用，是 Google 在设计 Cloud API 和其他 Google API 时遵循的指南。此设计指南在此处共享，以便为外部开发者提供信息，并使我们所有人更容易协同工作。

在设计 gRPC API 时，Google Cloud Endpoints 开发者可能会发现本指南特别有用，我们强烈建议此类开发者使用这些设计原则。但我们不强制要求使用本指南。您可以使用 Cloud Endpoints 和 gRPC，而无需遵循本指南。

本指南适用于 REST API 和 RPC API，尤其适用于 gRPC API。gRPC API 使用 Protocol Buffers 定义其 API 接口和 API 服务配置，以配置其 API 服务，包括 HTTP 映射、日志记录和监控。Google API 和 Cloud Endpoints gRPC API 使用 HTTP 映射功能进行 JSON/HTTP 到 Protocol Buffers/RPC 的转码。

本指南是一份活文档，随着时间的推移，我们会批准并采纳新的风格和设计模式，同时也会为本指南增加相关内容。本着这种精神，我们会一直完善本指南，并为 API 设计提供充足的艺术和工艺发挥空间。

本文档中使用的惯例

本文档中使用的要求级别关键字（“必须”、“不得”、“必需”，“应”、“不应”、“应该”、“不应该”、“建议”、“可以”和“可选”）将按 RFC 2119 中的描述进行解释。

在本文档中，这些关键字使用粗体突出显示。