I servizi API in genere utilizzano i file .proto per definire l'interfaccia API e i file .yaml per configurare il servizio API. Ogni servizio API deve avere una directory API all'interno di un repository API. La directory dell'API deve contenere tutti i file di definizione dell'API e gli script di compilazione.
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 compilazione.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 riferimento, ovvero la rappresentazione YAML del messaggio protogoogle.api.Service.prod.yaml: il file di configurazione del servizio delta di produzione.staging.yaml: il file di configurazione del servizio delta di staging.test.yaml: il file di configurazione del servizio delta di test.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 di interfaccia
v[0-9]*/*: ogni directory contiene una versione principale dell'API, principalmente i file proto e gli script di compilazione.{subapi}/v[0-9]*/*: ogni directory{subapi}contiene la definizione dell'interfaccia di una sotto-API. Ogni API secondaria 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 di tipo intype/*non devono avere modifiche che ne interrompono il funzionamento una volta rilasciate.
Le definizioni pubbliche delle API Google vengono pubblicate su GitHub, consulta il repository API Google. Per informazioni dettagliate sulla struttura della directory, consulta API di esempio di Service Infrastructure.