简介
这是联网 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 中的描述进行解释。
在本文档中，这些关键字使用粗体突出显示。
部分
面向资源的设计
如需了解如何为 RPC 和 REST API 实现以资源为导向的设计，请参阅 AIP-121。
资源名称
如需了解资源名称，请参阅 AIP-122。
标准方法
如需了解方法的一般信息，请参阅 AIP-130。
如需了解标准方法，请参阅以下 AIP：
- 对于
Get，请参阅 AIP-131 - 对于
List，请参阅 AIP-132 - 对于
Create，请参阅 AIP-133 - 对于
Update，请参阅 AIP-134 - 对于
Delete，请参阅 AIP-135
自定义方法
如需了解自定义方法，请参阅 AIP-136。
其他主题
如需了解以下主题，请参阅其相关 AIP。
- 如需了解标准字段，请参阅 AIP-148
- 如需了解错误，请参阅 AIP-193
- 如需了解设计模式，请参阅 AIP 设计模式指南
- 如需查看内嵌 API 文档，请参阅 AIP-192
- 如需了解如何使用 proto3，请参阅 AIP-191 的“语法”部分
- 如需了解版本控制，请参阅 AIP-185
- 如需了解向后兼容性，请参阅 AIP-180
- 如需了解文件结构，请参阅 AIP-191 的“文件布局”部分
- 如需查看术语的术语表，请参阅 AIP-9
如需了解以下主题，请参阅本指南中的相关页面。