API: Añadir Estado De Calidad A Módulos

¡Hola a todos! Hoy vamos a hablar de cómo podemos hacer nuestra API mucho más útil y transparente para ustedes, nuestros usuarios. Estamos proponiendo una mejora emocionante: extender la API para que devuelva el estado de calidad de cada módulo. Esto significa que no solo podrán ver la información básica de los módulos, sino que también podrán saber exactamente cuán "saludable" o "robusto" es cada uno, basándose en métricas automáticas. ¡Imaginen poder filtrar todos los módulos que cumplen con los más altos estándares de calidad de un vistazo! Eso es exactamente lo que buscamos lograr con esta funcionalidad.

¿Por Qué Necesitamos Esto? El Problema que Resuelve

Actualmente, nuestra API nos da una gran cantidad de información sobre los módulos disponibles, lo cual es fantástico. Sin embargo, hay un detalle importante que falta: una forma clara y directa de conocer el estado de calidad de cada módulo. Ustedes saben que tenemos procesos de Integración Continua (CI) que ejecutan reportes de calidad automáticamente. Estos reportes generan datos valiosos, pero actualmente, esa información no se refleja directamente en la API. Esto crea una desconexión. Los usuarios no tienen una manera sencilla de saber si un módulo ha pasado todas las pruebas de calidad, si tiene advertencias, o si necesita atención. Para resolver esto, proponemos extender la API para mostrar el estado de calidad (quality_state) de cada módulo y permitir el filtrado por este campo. Al hacer esto, alineamos perfectamente la información que ven en la API con los resultados de nuestros reportes automáticos de CI. Ya no tendrán que adivinar o buscar esta información en otros lugares; estará justo donde la necesitan, haciendo su trabajo más eficiente y sus decisiones más informadas. Esta mejora es crucial para cualquiera que dependa de la calidad y la confiabilidad de los módulos que ofrecemos. Pensamos en ustedes, los desarrolladores y administradores que utilizan nuestra plataforma, y queremos asegurarles que tienen las herramientas necesarias para tomar las mejores decisiones.

Nuestra Solución Propuesta: Visibilidad Total del Estado de Calidad

Para abordar la falta de visibilidad del estado de calidad, hemos ideado una solución elegante y directa: leer el reporte de calidad generado por CI y exponer el campo quality_state en la API, permitiendo además el filtrado por este estado. ¿Cómo funcionará esto en la práctica? Nuestro sistema de CI genera un archivo de reporte de calidad (actualmente ubicado en .evidence/iac-quality-report.json) después de ejecutar todas las verificaciones pertinentes. Lo que haremos es que nuestro backend de la API lea este archivo. Una vez que tengamos acceso a esta información, expondremos un nuevo campo llamado quality_state en la respuesta de la API para cada módulo. Este campo les dirá, de forma concisa, cuál es el estado de calidad del módulo (por ejemplo, "pass", "warning", "fail"). Pero eso no es todo, ¡queremos que sea aún más útil! También habilitaremos la capacidad de filtrar los módulos basándonos precisamente en este quality_state. Imaginen hacer una solicitud a la API y pedir solo los módulos que están en estado "pass", o aquellos que tienen "warning" para que puedan revisarlos. Además de implementar la funcionalidad principal, nos aseguraremos de que todo el proceso esté sólidamente respaldado. Esto incluye agregar pruebas unitarias para garantizar que la lectura del reporte y la exposición del campo funcionen como se espera, y actualizar nuestra documentación para que sepan exactamente cómo usar esta nueva funcionalidad de filtrado y qué esperar del campo quality_state. Creemos firmemente que esta solución traerá un valor inmenso, proporcionando transparencia y control sobre la calidad de los módulos que utilizan.

Pasos Clave para la Implementación: Tareas de Implementación Detalladas

Para que esta mejora sea una realidad, hemos desglosado el proceso en tareas específicas y manejables. Cada una de estas tareas es un paso crucial para asegurar que la nueva funcionalidad sea robusta, confiable y fácil de usar. Aquí están los puntos clave que abordaremos:

1. Leer .evidence/iac-quality-report.json en el backend: El primer paso es asegurarse de que nuestro servidor de API pueda acceder y procesar la información del reporte de calidad. Esto implica modificar la lógica del backend para que localice y lea el archivo .evidence/iac-iac-quality-report.json generado por el pipeline de CI. Necesitamos parsear este archivo para extraer los datos relevantes, en particular, el campo quality_state para cada módulo que se reporta.
2. Exponer quality_state y filtrado en la API: Una vez que los datos de calidad estén disponibles en el backend, el siguiente paso es hacerlos accesibles a través de la API. Esto significa modificar los endpoints existentes (o crear nuevos si es necesario) para incluir el campo quality_state en las respuestas de los módulos. Simultáneamente, implementaremos la lógica para permitir que los usuarios filtren las listas de módulos basándose en este nuevo campo. Por ejemplo, un usuario podría solicitar GET /modules?quality_state=pass para obtener solo los módulos que han pasado las pruebas de calidad.
3. Agregar pruebas unitarias y actualizar documentación: La calidad de nuestro código es tan importante como la calidad de los módulos que reportamos. Por lo tanto, es esencial agregar pruebas unitarias exhaustivas para validar que la lectura del reporte, la exposición del quality_state y la funcionalidad de filtrado operan correctamente bajo diversas condiciones. Esto nos dará confianza en la estabilidad de la nueva característica. Finalmente, pero no menos importante, debemos actualizar nuestra documentación. Esto incluye explicar claramente qué es el campo quality_state, cuáles son los posibles valores que puede tomar, y cómo utilizar la nueva opción de filtrado en las solicitudes a la API. Una buena documentación es clave para que todos puedan aprovechar al máximo esta mejora.

Criterios de Aceptación: ¿Cómo Sabremos Que Lo Hicimos Bien?

Para asegurarnos de que hemos cumplido con los objetivos de esta mejora y que la nueva funcionalidad es un éxito, hemos definido criterios de aceptación claros y medibles. Estos criterios actúan como nuestra lista de verificación para confirmar que todo funciona como se espera y que los usuarios obtendrán el valor prometido. Si cumplimos con estos puntos, sabremos que hemos entregado una solución que satisface las necesidades:

• El campo quality_state aparece en la respuesta de la API: Este es el criterio más directo. Al realizar una consulta a la API para obtener información sobre un módulo, esperamos ver un nuevo campo llamado quality_state en la estructura de datos devuelta. Este campo debe contener un valor representativo del estado de calidad del módulo, como "pass", "warning", o "fail", tal como se define en nuestros reportes de CI. La presencia y el formato correcto de este campo son fundamentales para la visibilidad que buscamos.
• Es posible filtrar módulos por estado de calidad: La capacidad de filtrar es lo que realmente potencia este nuevo campo. Debemos poder realizar solicitudes a la API especificando un quality_state deseado y recibir únicamente los módulos que coinciden con ese criterio. Por ejemplo, si consultamos por módulos con quality_state=pass, solo deberíamos ver aquellos que han superado todas las verificaciones de calidad. Poder filtrar por "warning" o "fail" también es crucial para tareas de auditoría y mantenimiento. Si ambas condiciones se cumplen, habremos logrado nuestro objetivo de hacer la API más funcional y alineada con las necesidades de control de calidad.

Contexto Adicional: La Conexión con la Integración Continua

Para entender completamente la importancia de esta mejora, es vital tener en cuenta el contexto adicional que la rodea. El reporte de calidad que alimentará nuestra API no surge de la nada. De hecho, se genera automáticamente en el workflow de CI. Esto significa que cada vez que se actualiza o se revisa un módulo, nuestro sistema de Integración Continua entra en acción, ejecutando un conjunto de pruebas y análisis diseñados para evaluar diversos aspectos de la calidad. Estos aspectos pueden incluir la conformidad con estándares de codificación, la ausencia de vulnerabilidades de seguridad conocidas, la eficiencia del código, y muchos otros factores relevantes. Una vez que el CI completa estas verificaciones, produce un reporte detallado, y de este reporte extraemos la información clave que se utiliza para informar el estado de los módulos en la API. Esta conexión directa entre el proceso automatizado de CI y la información expuesta en la API garantiza que los datos de calidad que ven sean siempre actuales y reflejen fielmente el resultado de las evaluaciones automáticas. No es una métrica estática, sino un reflejo dinámico del estado de salud de cada módulo. Al exponer este quality_state a través de la API, estamos abriendo una ventana a la salud de nuestra infraestructura de módulos, permitiendo a los usuarios tomar decisiones informadas y proactivas basadas en datos confiables y actualizados. Esta integración profunda con CI es lo que hace posible esta funcionalidad y asegura su relevancia y precisión.

Esperamos que esta propuesta de extender la API para incluir el estado de calidad de los módulos sea de gran valor para todos. Creemos que traerá una mayor transparencia y control, facilitando la gestión y el uso de nuestros recursos.

Para más información sobre prácticas de DevOps y CI/CD, les recomendamos visitar Red Hat DevOps y AWS CI/CD.