Estrutura do diretório

Os serviços de API geralmente usam arquivos .proto para definir a superfície da API e arquivos .yaml para configurar o serviço da API. Cada serviço de API precisa ter um diretório dentro de um repositório de APIs. O diretório da API deve conter todos os arquivos de definição de API e scripts de build.

Cada diretório da API terá o seguinte layout padrão:

  • Diretório da API

    • Pré-requisitos do repositório

      • BUILD - arquivo de criação
      • METADATA - arquivo de metadados de criação;
      • OWNERS - proprietários do diretório da API
      • README.md - as informações gerais sobre o serviço da API.
    • Arquivos de configuração

      • {service}.yaml: o arquivo de configuração do serviço de referência, que é a representação YAML da mensagem proto google.api.Service.
      • prod.yaml: o arquivo de configuração do serviço delta prod.
      • staging.yaml: o arquivo de configuração do serviço delta de teste.
      • test.yaml: o arquivo de configuração do serviço delta de teste.
      • local.yaml: o arquivo de configuração do serviço delta local.
    • Arquivos de documentação

      • doc/*: os arquivos de documentação técnica. Eles estarão no formato Markdown.
    • Definições de interface

      • v[0-9]*/*: cada diretório contém uma versão principal da API, principalmente os arquivos proto e os scripts de build.
      • {subapi}/v[0-9]*/*: cada diretório {subapi} contém a definição de interface de uma sub-API. Cada sub-API pode ter sua própria versão principal independente.
      • type/*: arquivos proto que contêm tipos que são compartilhados entre APIs diferentes, versões distintas da mesma API ou entre a API e a implementação do serviço. As definições de tipo em type/* não devem ter alterações interruptivas depois de serem lançadas.

As definições públicas da API do Google são publicadas no GitHub, consulte o repositório de APIs do Google. Para detalhes sobre a estrutura de diretórios, consulte API Service Infrastructure Example.