Estructura del directorio

Un directorio de API típico contiene archivos .proto, que definen la superficie de la API, y archivos .yaml, que configuran el servicio de la API. Usar este diseño te ayuda a mantener configuraciones de servicios coherentes e interfaces con versiones en todos los entornos. Cada servicio de API debe tener un directorio de API dentro de un repositorio de API, y el directorio de API debe contener todos los archivos de definición de API y los 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ón
    • METADATA: el archivo de compilación de metadatos
    • OWNERS: los propietarios del directorio de API
    • README.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 proto google.api.Service.
    • prod.yaml: el archivo de configuración del servicio delta de producción
    • staging.yaml: el archivo de configuración del servicio delta de etapa de pruebas
    • test.yaml: el archivo de configuración del servicio delta de prueba
    • local.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 en type/* 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.