这是联网 API 的常规设计指南。该 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 中的描述进行解释。
在本文档中,这些关键字使用粗体突出显示。
部分
- 基于资源的设计
- 资源名称
- 标准方法
- 自定义方法
- 标准字段
- 错误
- 命名规则
- 设计模式
- 文档
- 使用 proto3
- 版本控制
- 兼容字符
- 目录结构
- 文件结构
- 术语库