Estructura de directorios

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ó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. Para obtener detalles sobre la estructura de directorios, consulta API de ejemplo de la infraestructura de servicio.