Una directory API tipica contiene file .proto, che definiscono la superficie dell'API, e file .yaml, che configurano il servizio API. L'utilizzo di questo layout ti aiuta a mantenere configurazioni di servizio coerenti e interfacce con controllo delle versioni in tutti gli ambienti. Ogni servizio API deve avere una directory API all'interno di un repository API e la directory API deve contenere tutti i file di definizione API e gli script di build.
Ogni directory API deve avere il seguente layout standard:
Directory API
Prerequisiti del repository
BUILD: il file di build.METADATA: il file di metadati della build.OWNERS: i proprietari della directory API.README.md: le informazioni generali sul servizio API.
File di configurazione
{service}.yaml: il file di configurazione del servizio di base, ovvero la rappresentazione YAML del messaggio protogoogle.api.Service.prod.yaml- Il file di configurazione del servizio delta prod.staging.yaml: il file di configurazione del servizio delta di staging.test.yaml- The test delta service config file.local.yaml: il file di configurazione del servizio delta locale.
File di documentazione
doc/*: i file della documentazione tecnica. Devono essere in formato Markdown.
Definizioni delle interfacce
v[0-9]*/*: ogni directory di questo tipo contiene una versione principale dell'API, principalmente i file proto e gli script di build.{subapi}/v[0-9]*/*: ogni directory{subapi}contiene la definizione dell'interfaccia di una sotto-API. Ogni sotto-API può avere la propria versione principale indipendente.type/*: file proto contenenti tipi condivisi tra API diverse, versioni diverse della stessa API o tra l'API e l'implementazione del servizio. Le definizioni dei tipi intype/*non devono presentare modifiche che causano interruzioni una volta rilasciate.
Le definizioni delle API di Google pubbliche sono pubblicate su GitHub. Consulta il repository API di Google.