Directory Structure

API services typically use .proto files to define the API surface and .yaml files to configure the API service.

Each API service must have an API directory inside an API repository that contains its definition files and build scripts.

The API directory should have the following standard layout:

  • API directory

    • Repository prerequisites

      • BUILD - The build file.
      • METADATA - The build metadata file.
      • OWNERS - The API directory owners.
    • Configuration files

      • {service}.yaml - The baseline service config file, which is the YAML representation of the google.api.Service proto message.
      • prod.yaml - The prod delta service config file.
      • staging.yaml - The staging delta service config file.
      • test.yaml - The test delta service config file.
      • local.yaml - The local delta service config file.
    • Documentation files

      • README.md - The main readme file. It should contain the general production overview, technical description, etc.
      • doc/* - The technical documentation files. They should be in Markdown format.
    • Interface definitions

      • v[0-9]*/* - Each such directory contains a major version of the API, mainly the proto files and build scripts.
      • {subapi}/v[0-9]*/* - Each {subapi} directory contains interface definition of a sub-API. Each sub-API may have its own independent major version.
      • type/* - proto files containing types that are shared between different APIs, different versions of the same API, or between the API and service implementation. Type definitions under type/* should not have breaking changes once they are released.

Send feedback about...