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. The API directory should contain all API definition files and build scripts.

Each 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.
    • README.md - The general information about the API service.

  • 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

    • 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.

Public Google API definitions are published on GitHub, see Google APIs repository.