Directory structure

A typical API directory contains .proto files, which define the API surface, and .yaml files, which configure the API service. Using this layout helps you maintain consistent service configurations and versioned interfaces across environments. Each API service must have an API directory inside an API repository, and 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.

Previous
Introduction
Next
Changelog