I servizi API utilizzano in genere file .proto per definire la superficie API e file .yaml per configurare il servizio API. Ogni servizio API deve avere
una directory API all'interno di un repository API. La directory API deve
contenere tutti i file di definizione delle 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 di produzione.staging.yaml: il file di configurazione del servizio delta di staging.test.yaml: il file di configurazione del servizio di test delta.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 dell'interfaccia
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 Google pubbliche sono pubblicate su GitHub. Consulta il repository API Google.