Directory structure

API services typically use .proto files to define the API surface and .yaml files to configure the API service. Each API service musthave an API directory inside an API repository. The API directory shouldcontain all API definition files and build scripts.

Each API directory shouldhave 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/* shouldnot have breaking changes once they are released.

Public Google API definitions are published on GitHub, see Google APIs repository. For details of the directory structure, see Service Infrastructure Example API .