Normalmente, os serviços de API usam ficheiros .proto
para definir a superfície da API e ficheiros .yaml
para configurar o serviço de API. Cada serviço API tem de ter um diretório de APIs num repositório de APIs. O diretório da API deve
conter todos os ficheiros de definição da API e scripts de compilação.
Cada diretório de API deve ter o seguinte esquema padrão:
Diretório de APIs
Pré-requisitos do repositório
BUILD
- O ficheiro de compilação.METADATA
- O ficheiro de metadados de compilação.OWNERS
– Os proprietários do diretório de APIs.README.md
– As informações gerais sobre o serviço de API.
Ficheiros de configuração
{service}.yaml
: o ficheiro de configuração do serviço de base, que é a representação YAML da mensagem protogoogle.api.Service
.prod.yaml
: o ficheiro de configuração do serviço delta de produção.staging.yaml
: o ficheiro de configuração do serviço delta de preparação.test.yaml
: o ficheiro de configuração do serviço delta de teste.local.yaml
: o ficheiro de configuração do serviço delta local.
Ficheiros de documentação
doc/*
– Os ficheiros de documentação técnica. Devem estar no formato Markdown.
Definições de interface
v[0-9]*/*
- Cada diretório deste tipo contém uma versão principal da API, principalmente os ficheiros proto e os scripts de compilação.{subapi}/v[0-9]*/*
- Cada diretório{subapi}
contém a definição da interface de uma sub-API. Cada sub-API pode ter a sua própria versão principal independente.type/*
- Ficheiros proto que contêm tipos partilhados entre diferentes APIs, diferentes versões da mesma API ou entre a API e a implementação do serviço. As definições de tipos emtype/*
não devem ter alterações significativas após o lançamento.
As definições públicas das APIs Google são publicadas no GitHub. Consulte o repositório APIs Google.