Presentación de las herramientas

Apicurio: Definiendo Claramente tu Producto y APIs

Apicurio es una herramienta de código abierto que permite diseñar y gestionar APIs utilizando la especificación OpenAPI. Su enfoque en la definición clara y precisa de APIs proporciona una base sólida sobre la cual construir aplicaciones robustas y escalables. Al utilizar Apicurio, los equipos pueden:

  1. Establecer un Contrato Claro: Las especificaciones de la API actúan como un contrato entre el frontend y el backend, asegurando que todos los desarrolladores entiendan las expectativas y requisitos desde el principio. Y por tanto crear servidores de mocking para back y front.
  2. Facilitar la Colaboración: Al tener un documento centralizado que describe la API, los equipos pueden colaborar más eficazmente, reduciendo malentendidos y errores. Con los cambios, exportas tus definiciones y actualizas tus servidores de mocking.
  3. Mejorar la Calidad del Producto: Una especificación bien definida ayuda a identificar problemas potenciales en las etapas iniciales del desarrollo, mejorando la calidad del producto final.

Además proporcionada unas funcionalidades adicionales muy interesantes:

  • Exposición de Esquemas de Clientes: Apicurio permite gestionar no solo APIs, sino también esquemas de eventos y mensajes, facilitando la exposición de estos de manera clara y organizada.
  • Despliegue Separado y Control de Versiones: La herramienta permite el despliegue por separado de diferentes esquemas, manteniendo un control de versiones preciso que asegura que las actualizaciones se realicen de manera controlada y sin afectar otros componentes.
  • Validación: Apicurio incorpora funcionalidades de validación que aseguran que las especificaciones cumplan con los estándares establecidos antes de ser implementadas, reduciendo errores y mejorando la consistencia.

Apicurio no solo mejora la definición y gestión de APIs, sino que también facilita una mejor colaboración, control de versiones y validación, asegurando un desarrollo más eficiente y productos de mayor calidad.

Kiota de Microsoft: Generación Automática de Clientes de API

Una vez que las APIs están definidas claramente con Apicurio, el siguiente paso es implementar clientes que puedan interactuar con estas APIs. Aquí es donde entra Kiota de Microsoft. Kiota es una herramienta que genera automáticamente código de cliente para APIs a partir de documentos OpenAPI. Esto ofrece varios beneficios:

  1. Ahorro de Tiempo: La generación automática de clientes de API elimina la necesidad de escribir manualmente el código repetitivo y propenso a errores, acelerando el proceso de desarrollo.
  2. Consistencia y Mantenimiento: Al utilizar una herramienta automatizada, se asegura que el código generado sea consistente, lo cual es crucial para el mantenimiento a largo plazo.
  3. Foco en la Lógica de Negocio: Al reducir la carga de trabajo asociada con la creación de clientes de API, los desarrolladores pueden centrarse más en la lógica de negocio y características innovadoras de la aplicación.

El ejemplo

Supongamos que estás desarrollando una aplicación de gestión de tareas que permite a los usuarios crear, actualizar y eliminar tareas. Aquí es cómo podrías utilizar Apicurio y Kiota en este proceso:

Paso 1: Definición de la API con Apicurio

Primero, utilizas Apicurio para definir la API de tu aplicación. Imagina que tienes las siguientes operaciones básicas:

  • GET /tasks: Recuperar todas las tareas.
  • POST /tasks: Crear una nueva tarea.
  • PUT /tasks/{id}: Actualizar una tarea existente.
  • DELETE /tasks/{id}: Eliminar una tarea.

Con Apicurio, defines cada uno de estos endpoints, especificando los parámetros, los esquemas de datos, las respuestas esperadas, y cualquier detalle de autenticación necesario. Este documento OpenAPI actúa como un contrato claro que todos los miembros del equipo pueden entender y seguir

Para hacer una prueba, te puedes instalar en local APICURITO.

Tambien puedes usar una IA Generativa con un pront muy sencillo:

Pero yo lo usaría como primera versión, que me generer un fichero inicial y luego lo depuro en Apicurio. Apicurio es para trabajar de forma colaborativa en un registro de APIs.

Paso 2: Generación del Cliente de API con Kiota

Una vez que la API está definida, utilizas Kiota para generar automáticamente el cliente de API en tu lenguaje de programación preferido, digamos Python. Kiota toma el documento OpenAPI que creaste con Apicurio y genera el código necesario para interactuar con tu API.

Por ejemplo, Kiota podría generar una clase TaskClient con métodos como get_tasks(), create_task(task_data), update_task(task_id, task_data) y delete_task(task_id). Estos métodos encapsulan las llamadas HTTP necesarias, manejan las respuestas y errores, y están listos para ser utilizados en tu aplicación.

No voy a copiar y pegar un magnifico ejemplod de Microsoft de .NET: Build API clients for .NET, en el podrás ver paso a paso como generar el código necesario, si desarrollas en Go, Java, PHP, Python y TS, tambien tienes los ejemplos.

Paso 3: Integración en tu Aplicación

Con el cliente de API generado, puedes integrarlo directamente en tu aplicación de gestión de tareas. Esto significa que el equipo de desarrollo puede enfocarse en implementar la lógica de negocio, como la interfaz de usuario y las características específicas, sin preocuparse por los detalles de cómo interactuar con la API.

Beneficio: Aceleración del Desarrollo

Al utilizar OpenAI, Apicurio y Kiota:

  • Ahorro de Tiempo: Se reduce el tiempo dedicado a escribir y probar código de cliente de API manualmente.
  • Consistencia: El código generado automáticamente es consistente y menos propenso a errores humanos.
  • Enfoque en Innovación: Los desarrolladores pueden dedicar más tiempo a mejorar la funcionalidad y la experiencia del usuario.
El Impacto de la Automatización y la IA: Un Ahorro del 25%

Al integrar Apicurio para la definición de APIs y Kiota para la generación de clientes, se puede obtener un ahorro notable en tiempo y recursos en el desarrollo de software. Según mis propias estimaciones, este enfoque podría reducir el esfuerzo de desarrollo en un 25% (a continuación explicaré el reto que me propuse). Esta reducción no solo permite a los equipos entregar productos más rápidamente, sino también mejorar la calidad de los mismos. Si bien no he podido medir el tiempo exacto que perdemos en las discusiones y consensos entre el equipo de frontend, backend y el Product Owner para definir bien las APIs, es evidente que estas herramientas facilitan el proceso.

Además, la incorporación de herramientas de inteligencia artificial puede amplificar este ahorro aún más, al automatizar tareas adicionales y ofrecer sugerencias inteligentes durante el desarrollo, lo que optimiza aún más los recursos y el tiempo empleado.

El reto consistió en comparar dos enfoques diferentes para el desarrollo de APIs, con el objetivo de evaluar la eficiencia y efectividad de cada uno. Se trató de un ejercicio personal en el que me propuse desarrollar un conjunto de APIs de dos maneras distintas:

  1. Desarrollo Tradicional en .NET desde Cero:
    • En este enfoque, construí las APIs manualmente utilizando .NET, desde la definición de los endpoints hasta la implementación completa del código. Esto implicó diseñar la estructura de datos, escribir la lógica de negocio, manejar las solicitudes HTTP y gestionar las respuestas, todo sin el uso de herramientas automatizadas.
  2. Desarrollo Automatizado con OpenAI, Apicurio y Kiota:
    • OpenAI: Utilicé herramientas de inteligencia artificial para asistir en la generación de ideas y optimización del código, lo que me ayudó a mejorar la calidad y eficiencia del desarrollo.
    • Apicurio: Importé las APIs de que me dio la IA y luego comencé a dejar más finlas esta APIs en Apicurio, lo que me permitió crear especificaciones claras y precisas en formato OpenAPI. Esto facilitó el entendimiento de la estructura de las APIs desde el principio (logicamente no colaboré con nadie).
    • Kiota: A partir de las especificaciones creadas con Apicurio, utilicé Kiota para generar automáticamente los clientes de API necesarios. Este paso automatizó gran parte del trabajo repetitivo y propenso a errores, como la generación de código para manejar las solicitudes y respuestas HTTP.

Nota: No he realizados test unitarios en ninguno de los ejemplos, si llego a incluir los test via IA en la segunda aproximación, el porcentaje de ahorro de tiempo es mayor.

Resultados del Reto: Al comparar ambos enfoques, encontré que el uso de OpenAI, Apicurio y Kiota ofreció un ahorro significativo en tiempo y esfuerzo, calculado en aproximadamente un 25%. Esta metodología no solo aceleró el proceso de desarrollo, sino que también mejoró la calidad y consistencia del código generado. Sin embargo, no pude medir el tiempo exacto ahorrado en la fase de consenso y definición de APIs entre los equipos de frontend, backend y el Product Owner, aunque es evidente que la claridad  que proporciona Apicurio ayuda a reducir fricciones en esta etapa.

Conclusión

En un entorno de desarrollo donde cada día cuenta en la velocidad de entrega de valor al cliente, estas herramientas representan una ventaja estratégica. Al permitir que los equipos definan claramente sus productos y APIs, y luego generen automáticamente el código necesario, estas herramientas ayudan a acelerar el ciclo de desarrollo de software.