Stay organized with collections
Save and categorize content based on your preferences.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-03-05 UTC."],[[["API services utilize `.proto` files for API definition and `.yaml` files for service configuration."],["Each API service must reside in an API directory within an API repository, containing all definition files and build scripts."],["An API directory should follow a standard layout including repository prerequisites, configuration files, documentation files, and interface definitions, like versioned sub-API directories, and type files for shared proto files."],["Public Google API definitions are available on the [Google APIs](https://github.com/googleapis/googleapis) GitHub repository, as seen with the [Service Infrastructure Example API](https://github.com/googleapis/googleapis/tree/master/google/example/endpointsapis)."]]],[]]
