Struttura delle directory

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 proto google.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 in type/* 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.