Uso de DevOps y CI/CD para publicar API

  • Artículo

SE APLICA A: todos los niveles de API Management

Con el valor estratégico de las API en la empresa, la adopción de técnicas de integración continua (CI) e implementación (CD) de DevOps se ha convertido en un aspecto importante del desarrollo de API. En este artículo se describen las decisiones que debe tomar para adoptar principios de DevOps para la administración de las API.

Api DevOps consta de tres partes:

Diagrama que ilustra el flujo de API DevOps.

A continuación se describe cada parte de la canalización de DevOps de API.

Definición de API

Un desarrollador de API escribe una definición de API proporcionando una especificación, una configuración (como registro, diagnósticos y configuración de back-end) y directivas que se aplicarán a la API. La definición de API proporciona la información necesaria para aprovisionar la API en un servicio de Azure API Management. La especificación puede basarse en una especificación de API basada en estándares (como WSDL, OpenAPI o GraphQL), o bien se puede definir mediante las API de Azure Resource Manager (ARM) (por ejemplo, una plantilla de ARM que describe la API y las operaciones). La definición de la API cambiará con el tiempo y se debe considerar "código fuente". Asegúrese de que la definición de la API se almacena en el control de código fuente y que tiene la revisión adecuada antes de la adopción.

Hay varias herramientas para ayudar a generar la definición de api:

  • Azure API Ops Toolkit proporciona un flujo de trabajo basado en un sistema de control de código fuente de Git (como GitHub o Azure Repos). Usa un extractor para generar una definición de API que, después, un publicador aplica a un servicio de API Management de destino. APIOps admite las API REST y GraphQL en este momento.
  • La herramienta dotnet-apim convierte una definición YAML bien formada en una plantilla de ARM para su posterior implementación. La herramienta se centra en las API REST.
  • Terraform es una alternativa a Azure Resource Manager para configurar recursos en Azure. Puede crear una configuración de Terraform (junto con directivas) para implementar la API de la misma manera que se crea una plantilla de ARM.

También puede usar herramientas basadas en IDE para editores como Visual Studio Code para generar los artefactos necesarios para definir la API. Por ejemplo, hay más de 30 complementos para editar archivos de especificación de OpenAPI en Visual Studio Code Marketplace. También puede usar generadores de código para crear los artefactos. El lenguaje CADL permite crear fácilmente bloques de creación de alto nivel y, a continuación, compilarlos en un formato de definición de API estándar, como OpenAPI.

Aprobación de API

Una vez que se haya generado la definición de API, el desarrollador enviará la definición de API para su revisión y aprobación. Si usa un sistema de control de código fuente basado en Git (como GitHub o Azure Repos), el envío se puede realizar a través de la solicitud de incorporación de cambios. Una solicitud de incorporación de cambios informa a otros de los cambios que se han propuesto en la definición de la API. Una vez confirmadas las puertas de aprobación, un aprobador combinará la solicitud de incorporación de cambios en el repositorio principal para indicar que la definición de API se puede implementar en producción. El proceso de solicitud de incorporación de cambios permite al desarrollador corregir los problemas encontrados durante el proceso de aprobación.

Tanto GitHub como Azure Repos permiten configurar canalizaciones de aprobación que se ejecutan cuando se envía una solicitud de incorporación de cambios. Puede configurar las canalizaciones de aprobación para ejecutar herramientas como:

  • Linters de especificación de API, como Espectral, para asegurarse de que la definición cumple los estándares de API requeridos por la organización.
  • Detección de cambios importantes mediante herramientas como openapi-diff.
  • Herramientas de auditoría y evaluación de seguridad. OWASP mantiene una lista de herramientas para el examen de seguridad.
  • Marcos de pruebas de API automatizadas, como Newman, un ejecutor de pruebas para colecciones de Postman.

Nota:

Las API de Azure deben cumplir un conjunto estricto de directrices que puede usar como punto de partida para sus propias directrices de API. Hay una configuración Spectral para aplicar las directrices.

Una vez que se han ejecutado las herramientas automatizadas, el ojo humano revisa la definición de la API. Las herramientas no detectarán todos los problemas. Un revisor humano garantiza que la definición de la API cumpla los criterios de la organización para las API, incluido el cumplimiento de las directrices de seguridad, privacidad y coherencia.

Publicación de API

La definición de API se publicará en un servicio API Management a través de una canalización de versión. Las herramientas que se usan para publicar la definición de API dependen de la herramienta utilizada para generar la definición de API:

¿Puedo usar otros sistemas de control de código fuente y CI/CD?

Sí. El proceso descrito funciona con cualquier sistema de control de código fuente (aunque las operaciones de API requieren que el sistema de control de código fuente esté basado en Git). Del mismo modo, puede usar cualquier plataforma de CI/CD siempre que se pueda desencadenar mediante una comprobación y ejecutar herramientas de línea de comandos que se comunican con Azure.

Procedimientos recomendados

No hay ningún estándar del sector para configurar una canalización de DevOps para publicar API, y ninguna de las herramientas mencionadas funcionará en todas las situaciones. Sin embargo, vemos que la mayoría de las situaciones se tratan mediante una combinación de las siguientes herramientas y servicios:

  • Azure Repos almacena las definiciones de API en un repositorio git.
  • Azure Pipelines ejecuta los procesos automatizados de aprobación de API y publicación de API.
  • Azure API Ops Toolkit proporciona herramientas y flujos de trabajo para publicar API.

Hemos visto el mayor éxito en las implementaciones de clientes y se recomiendan los procedimientos siguientes:

  • Configure GitHub o Azure Repos para el sistema de control de código fuente. Esta opción también determinará la elección del ejecutor de canalización. GitHub puede usar Azure Pipelines o Acciones de GitHub, mientras que Azure Repos deben usar Azure Pipelines.
  • Configure un servicio de Azure API Management para cada desarrollador de API para que pueda desarrollar definiciones de API junto con el servicio de API. Use la SKU de consumo o desarrollador al crear el servicio.
  • Use fragmentos de directiva para reducir la nueva directiva que los desarrolladores necesitan escribir para cada API.
  • Use valores con nombre y back-ends para asegurarse de que las directivas son genéricas y se pueden aplicar a cualquier instancia de API Management.
  • Use Azure API Ops Toolkit para extraer una definición de API en funcionamiento del servicio para desarrolladores.
  • Configure un proceso de aprobación de API que se ejecute en cada solicitud de incorporación de cambios. El proceso de aprobación de LA API debe incluir la detección de cambios importantes, el linting y las pruebas automatizadas de API.
  • Use el publicador de Azure API Ops Toolkit para publicar la API en el servicio de producción API Management.

Consulte Implementaciones automatizadas de API con operaciones de API en el Centro de arquitectura de Azure para más información sobre cómo configurar y ejecutar una canalización de implementación de CI/CD con operaciones de API.

Referencias