Por lo general, los servicios de API usan archivos .proto para definir la superficie de la API y archivos .yaml a fin de configurar el servicio de API. Cada servicio de API debe tener un directorio de API dentro de un repositorio de API. El directorio de API debe contener todos los archivos de definición de la API y las secuencias de comandos de compilación.
Cada directorio de API debería tener el siguiente diseño estándar:
Directorio de API
Requisitos previos del repositorio
BUILD: el archivo de compilaciónMETADATA: el archivo de compilación de metadatosOWNERS: los propietarios del directorio de APIREADME.md: la información general sobre el servicio de API.
Archivos de configuración
{service}.yaml: el archivo de configuración del servicio de referencia, que es la representación YAML del mensaje protogoogle.api.Service.prod.yaml: el archivo de configuración del servicio delta de producciónstaging.yaml: el archivo de configuración del servicio delta de etapa de pruebastest.yaml: el archivo de configuración del servicio delta de pruebalocal.yaml: el archivo de configuración del servicio delta local.
Archivos de documentación
doc/*: los archivos de documentación técnica. Deberían estar en el formato Markdown
Definiciones de interfaz
v[0-9]*/*: cada directorio contiene una versión principal de la API, en particular, de los archivos de protocolo y las secuencias de comandos de compilación.{subapi}/v[0-9]*/*: cada directorio{subapi}contiene la definición de interfaz de una subAPI. Cada subAPI puede tener su propia versión principal independiente.type/*: archivos proto que contienen tipos que se comparten entre diferentes API, diferentes versiones de la misma API o entre la API y la implementación del servicio. Las definiciones de tipo entype/*no deben tener cambios rotundos una vez que se lancen.
Las definiciones de las API de Google públicas se publican en GitHub, consulta el repositorio de API de Google. Para obtener detalles sobre la estructura de directorios, consulta API de ejemplo de la infraestructura de servicio.