简介
这是联网 API 的通用设计指南。它自 2014 年起在 Google 内部使用，是 Google 在设计 Cloud API 和其他 Google API 时遵循的指南。我们在此公开此设计指南，目的是为外部开发者提供信息，使我们所有人都能更轻松地协同工作。 Cloud Endpoints 开发者可能会发现本指南在设计 gRPC API 时特别有用，我们强烈建议此类开发者遵循这些设计原则。不过，我们并不强制要求使用本指南。您可以使用 Cloud Endpoints 和 gRPC，而无需遵循本指南。 本指南同时适用于 REST API 和 RPC API，尤其适用于 gRPC API。gRPC API 使用 Protocol Buffers 定义其 API 表面 (surface) 和 API 服务配置，以配置其 API 服务，包括 HTTP 映射、日志记录和监控。Google API 和 Cloud Endpoints gRPC API 使用 HTTP 映射功能进行 JSON/HTTP 到 Protocol Buffers/RPC 的转码。 本指南是一份活文档，随着时间的推移，我们会采纳和批准新的风格和设计模式，为本指南增加相关内容。本着这种精神，我们会不断完善本指南，并为 API 设计的艺术和技巧提供充足的空间。
本指南中使用的惯例
本文档中使用的要求级别关键字（“必须”、“不得”、“必需”，“应”、“不应”、“应该”、“不应该”、“建议”、“可以”和“可选”）将按 RFC 2119 中的描述进行解释。 在本文档中，这些关键字使用粗体突出显示。