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 thegoogle.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 undertype/*
should not 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.