谷歌API 设计指南

目录结构

Preview

API 服务通常使用 .proto 文件来定义 API 接口,并使用 .yaml 文件来配置 API 服务。每个 API 服务必须在 API 代码库中有一个 API 目录。API 目录应该包含所有 API 定义文件和构建脚本。 每个 API 目录应该具有以下标准布局:

  • API 目录
    • 代码库必要条件
      • BUILD:构建文件。
      • METADATA:构建元数据文件。
      • OWNERS:API 目录所有者。
      • README.md:有关 API 服务的常规信息。
    • 配置文件
      • {service}.yaml:基准服务配置文件,google.api.Service proto 消息的 YAML 表示法。
      • prod.yaml:生产环境增量服务配置文件。
      • staging.yaml:模拟环境增量服务配置文件。
      • test.yaml:测试环境增量服务配置文件。
      • local.yaml:本地环境增量服务配置文件。
    • 文档文件
      • doc/*:技术文档文件。它们应采用 Markdown 格式。
    • 接口定义
      • v[0-9]*/*:每个这样的目录都包含 API 的主要版本,主要是 proto 文件和构建脚本。
      • {subapi}/v[0-9]*/*:每个 {subapi} 目录都包含子 API 的接口定义。每个子 API 可以有自己的独立主要版本。
      • type/*:proto 文件,包含在不同 API 之间、同一 API 的不同版本之间或 API 与服务实现之间共享的类型。type/* 下的类型定义一旦发布就不应该有破坏性更改。

公共 Google API 定义在 GitHub 上发布,请参阅 Google API 代码库。如需详细了解目录结构,请参阅 Service Infrastructure 示例 API注意:如果您是 Cloud Endpoints 开发者,则可以按照配置 gRPC 服务的说明配置您的 API 服务。