Gobernanza de API

Completado

La gobernanza de API se define como el procedimiento de definir y aplicar estándares, directivas y procesos a gran escala en todas las API de la organización. API Center le permite hacerlo:

• Con un seguimiento de los metadatos de API, incluidos el título de la API, la descripción, las versiones, las definiciones y las implementaciones. Además, puede especificar sus propios metadatos de API personalizados ( como la información del sitio activo, el repositorio de control de código fuente, etc.) para realizar un seguimiento de los metadatos importantes para su organización (que se muestran en un módulo anterior).
• Garantizando que todas las API están diseñadas para ajustarse a las filosofías de diseño de API de la organización
• Garantizando la detección oportuna de las versiones de API con cambios importantes para implementaciones sin problemas y comunicación a los consumidores de API

En esta unidad, veremos cómo API Center permite configurar la gobernanza de API a escala.

Requisitos previos

Para controlar las API con API Center, deberá hacer lo siguiente:

1. Instale la CLI de Azure.
2. Instalar Azure Developer CLI (azd).
3. Registrar el proveedor de recursos Event Grid en su suscripción. Si necesita registrar el proveedor de recursos de Event Grid, consulte Suscripción a eventos publicados por un asociado con Azure Event Grid.

Conformidad con el diseño de la API

Los equipos de la plataforma de API suelen ser responsables de definir un conjunto de directrices para los productores de API. API Center permite codificar directrices de API mediante la definición de reglas con el motor de linting de código abierto Spectral. De forma predeterminada, API Center incluye una regla de Spectral proporcionada, pero siempre puede crear su propia o aprovechar la gran comunidad de conjuntos de reglas de código abierto. Cada vez que se carga una definición de API, API Center ejecuta el linter Spectral mediante el conjunto de reglas proporcionado para comprobar la definición de API para que se ajuste a la regla. Se genera un informe de cumplimiento de API que puede ver en el centro de API.

Para configurar la conformidad del diseño de API para su organización:

1. Clone el Repositorio de GitHub y ábralo en Visual Studio Code.

2. Cambie el directorio a la carpeta APICenter-Analyzer del repositorio.

3. En la carpeta resources/rulesets, puede encontrar un archivo oas.yaml. Este archivo refleja la guía de estilo de API actual y se puede modificar en función de las necesidades y requisitos de su organización.

4. Autentíquese con Azure Developer CLI y la CLI de Azure mediante los siguientes comandos:

   azd auth login
   
   az login
   

5. Ejecute el comando siguiente para implementar la infraestructura de linting en la suscripción de Azure.

   azd up
   

6. Siga las indicaciones para proporcionar la información y la configuración de implementación necesarias, como el nombre del entorno y el nombre del centro de API. Para obtener más información, consulte Ejecución del ejemplo mediante Azure Developer CLI (azd).

   Nota:

   La implementación puede tardar unos minutos.

7. Una vez completada la implementación, vaya al centro de API en Azure Portal. En el menú de la izquierda, seleccione Eventos>Suscripciones a eventos para ver la suscripción a eventos que se creó.

Ahora puede cargar un archivo de definición de API en el centro de API para desencadenar la suscripción a eventos y ejecutar el motor de linting.

Gobernanza de API de desplazamiento a la izquierda

Las iniciativas de gobernanza más exitosas siempre incluyen a los desarrolladores. Al aplicar principios tradicionales de desplazamiento a la izquierda, los equipos de plataforma de API pueden asegurarse de que los productores de API sepan exactamente qué requisitos deben cumplir para publicar las API al principio del ciclo de desarrollo. Esto ahorra un tiempo de desarrollo valioso al reducir la necesidad de corregir las API no compatibles más adelante en el ciclo de desarrollo.

La extensión API Center para Visual Studio Code proporciona a los productores de API una experiencia para ejecutar comprobaciones de conformidad de diseño de API directamente en Visual Studio Code a medida que se compila la API. Además, los productores de API pueden usar la característica de detección de cambios importantes para detectar cuándo un cambio puede dar lugar a un chat importante para los consumidores de API.

Conformidad del diseño de API en Visual Studio Code

La extensión de API Center se integra con Spectral, un linter JSON/YAML que admite OpenAPI y un conjunto de reglas personalizados. La extensión permite a los desarrolladores seguir estrictamente la guía de estilo de API proporcionada o recomendada, lo cual garantiza la coherencia en todas las API que se desarrollan en diferentes equipos.

Nota:

Debe instalar las extensiones de API Center y Espectral para usar esta funcionalidad.

Para activar,

1. Utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos. Escriba Azure API Center: Establecer guía de estilo de API activa y pulse Intro.
2. Seleccione una de las reglas predeterminadas proporcionadas o, si su organización ya dispone de una guía de estilo, utilice Seleccionar archivo local o Introducir URL remota para especificar el conjunto de reglas activo en Visual Studio Code. Pulse Intro.

Una vez establecida una guía de estilo de API activa, al abrir cualquier archivo de especificación basado en OpenAPI o AsyncAPI se desencadena una operación de linting local en Visual Studio Code. Los resultados se muestran en línea en el editor y, en la ventana Problemas (Ver > Problemas o Ctrl+Mayús+M).

Detección de cambios importantes en Visual Studio Code

El envío de versiones de API que interrumpen los flujos de trabajo de producción del consumidor da lugar a una falta de confiabilidad y pérdida de confianza. La extensión de API Center, con Optic, permite a los desarrolladores comparar fácilmente dos versiones de API y detectar los cambios importantes introducidos en la API antes de la implementación.

Nota:

Debe instalar Optic para usar esta funcionalidad. Instálelo con el comando siguiente.

*npm install -g @useoptic/optic*

A continuación,

1. Utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos. Escriba Centro de API de Azure: detectar cambio importante y presione Entrar.
2. Seleccione el primer documento de especificación de API que se va a comparar. Entre las opciones válidas se incluyen las especificaciones de API que se encuentran en el centro de API, un archivo local o el editor activo en Visual Studio Code.
3. Seleccione el segundo documento de especificación de API que se va a comparar. Entre las opciones válidas se incluyen las especificaciones de API que se encuentran en el centro de API, un archivo local o el editor activo en Visual Studio Code.

Visual Studio Code abre una vista de diferencias entre las dos especificaciones de API. Los cambios importantes se muestran en línea en el editor y, en la ventana Problemas (Ver > Problemas o Ctrl+Mayús+M).