Arazzo Specification, ¿qué es y para qué sirve?

En un post anterior comentamos las tendencias en el ámbito API de este 2024, y uno de los puntos candentes es la especificación de API Workflows.

En el blog ya hemos hablado largo y tendido de APIs pero, a medida que avanza el año, hemos comprobado cómo el reciente auge de la IA Generativa ha potenciado el interés en el mundo de la APIficación, derivado de su relevante papel en este contexto.

Es indudable que la unión entre ambos mundos, IA Generativa y APIs, conforman un núcleo de innovación tecnológica con muchísimo potencial.

Independientemente de la empresa o el sector, incluso del tipo de arquitectura, se necesitan mecanismos solventes para los consumidores de las APIs, ya sean sistemas, humanos o IA, y huelga decir que esa solvencia en muchas ocasiones brilla por su ausencia.

Es en este sentido, el de facilitar el consumo de las APIs, donde surge la figura de la especificación de API Workflows, cuyo objetivo fundamental es describir y documentar procesos de negocio de una forma estandarizada. Es decir, se convierten en un componente clave por dos motivos:

• Son un enlace entre la IA Generativa y las APIs
• Buscan de forma inherente mejorar la experiencia del desarrollador

¿En qué consiste?

API Workflows Specification es un framework pionero que busca definir y documentar flujos de llamadas APIs, es decir, estandariza la secuencia de llamadas a varias APIs, incorporando condiciones de éxito para cada paso e instrucciones para transferir la respuesta al siguiente eslabón de la cadena.

Esta trabajo forma parte de la iniciativa OpenAPI y permite a los consumidores hacer que los endpoints no sólo sean más fáciles de entender, sino también de consumir e integrar, lo que facilita su adopción y uso tanto para los consumidores tradicionales como para la nueva ola de consumidores de IA Generativa.

Objetivos

La iniciativa OpenAPI ha trabajado en esta primera versión de API Workflows en la definición y resolución de una serie problemas habituales que marcan los objetivos iniciales de la línea de trabajo, que son:

• Proporcionar una “fórmula” determinista para consumir varias APIs. El factor determinante a la hora de consumir APIs es la integración, como se demuestra en el informe de Postman, donde el 67% de los encuestados recalcó como punto clave la integración entre aplicaciones internas, programas o sistemas.

• Actuar como documentación viva y evitar la dependencia con otro tipo de recursos para elaborar dicha documentación.
  No es algo nuevo el hecho de que uno de los mayores obstáculos a la hora de consumir las APIs son la deficiente o incluso carente documentación de las mismas, hecho que se constata en los informes de Postman y SmartBear:
  “El 52% de los encuestados dijo que la falta de documentación era el mayor problema.”

“Solo el 32% de los encuestados dijo que consideraba sus APIs bien documentadas.”

• Proporcionar un mecanismo coherente e interoperable para que los modelos de IA interactúen con las API.
  La utilización de este tipo de herramientas en el mundo del desarrollo ya se ha convertido en algo habitual, y por supuesto en el mundo API no iba a ser menos, como puede verse en los siguientes datos:
  “El 60% de los encuestados afirmaron que empleaban estas herramientas. Los usos más comunes eran encontrar errores en el código, producir código e instrucciones de codificación y, también, en la generación de la documentación.”

Estructura de la especificación

La especificación de API Workflows se encuentra en la versión 1.0.0 pre-release. Es decir, todavía se está trabajando por parte de la iniciativa en liberar su primera versión oficial.

En esta especificación se define la estructura del documento o documentos que describen los flujos de llamadas en formato tanto JSON como Yaml, y en la siguiente imagen puede verse el detalle de sus componentes de forma muy resumida:

Un ejemplo paso a paso de la especificación para entender mejor la estructura sería: presentación de Frank Kilcommins de la que hemos extraído la imagen anterior o ejemplos de la iniciativa OpenAPI, donde están estandarizando flujos típicos que se encuentran en escenarios reales para usarlos como base.

Su funcionamiento es muy sencillo: dentro de cada workflow se definen los parámetros o entradas posibles para dicho flujo y la lista de acciones o pasos que se conforman en base a ciertas condiciones, tal y como se muestra en la siguiente imagen:

Si hablamos de testing, ¿en qué puede ayudarnos?

En el ámbito del testing, la utilización de API Workflows permite resolver uno de los retos más comunes que nos encontramos: la validación de flujos de información. Con las herramientas actuales, dicha validación conlleva mucho esfuerzo por parte de los equipos, sea cual sea su toolkit de pruebas.

El enfoque actual está basado en pruebas individuales de endpoint a nivel de aceptación y /o integración en lugar de enfocarlo en procesos de negocio, ya que elaborar esos escenarios completos requiere mucho esfuerzo y es un tipo de prueba que no se realiza. En el mejor de los casos, se ejecuta para flujos de negocio críticos, pero no es lo habitual.

La utilización de API Workflows nos permite definir escenarios de prueba legibles por sistemas que contemplan toda la información necesaria: operaciones, orden, expectativas… sin tener que dedicar tiempo y esfuerzo en implementar ese proceso.

Esto permite crear planes de pruebas basados en escenarios del mundo real, no en pruebas aisladas, siendo estos escenarios más eficaces y garantes del comportamiento que se espera desde el punto de vista del usuario final.

Y cómo no, qué papel juega la IA Generativa en este ámbito

A lo largo del artículo hemos hablado de la IA generativa, y no es una casualidad. La sinergia que existe entre la especificación de API Workflows y la IA Generativa es indudable, ya que los workflows sirven como enlace entre las funcionalidades que se ofrecen a través de las APIs y las capacidades de procesamiento de las IA que los consumen.

Es decir, los workflows no solo facilitan el consumo a los desarrolladores o sistemas tradicionales, si no que proporcionan una interfaz estandarizada para que las IA Generativas interactúen de una forma más eficaz, presentando las siguientes ventajas:

• Facilita y estandariza las interacciones

Desde el punto de vista de la IA como consumidora de los servicios, resulta clave disponer de un flujo compresible y definido de las interacciones y llamadas para las APIs, permitiendo ejecutar las operaciones complejas dentro de un marco coherente y uniforme de los servicios, para lo cual la estandarización es imprescindible.

• Acelera la adopción y uso de la IA Generativa

El hecho de simplificar la interacción permite que los desarrolladores puedan crear aplicaciones aprovechando las capacidades que ofrece la IA generativa, no solo acelerando el tiempo de desarrollo, sino incluyendo nuevas funcionalidades basadas en la innovación.

• Fomenta la seguridad

Los API Workflows permiten garantizar que las operaciones realizadas desde las IA Generativas a través de las APIs expuestas sean seguras y cumplan la normativa definida, siguiendo protocolos de seguridad y requisitos de cumplimiento validados, minimizando así riesgos y potenciales fugas de información.

Conclusiones

A modo resumen, podemos decir que el trabajo realizado hasta ahora por la iniciativa OpenAPI con la especificación de API Workflows, y que todavía continúa, permite:

• Simplificar el consumo de las APIs, al plantear una “receta” clara y determinista para usar APIs de forma conjunta y no aislada como hasta ahora. Reduce considerablemente la curva de aprendizaje y mejora la eficiencia a la hora de integrarse.
• Consultar documentación dinámica y viva, ya que garantiza que la especificación está actualizada, es fiable y precisa con la funcionalidad que expone.
• Mejorar la experiencia del desarrollador, al ser un nexo de unión entre los proveedores de API y sus consumidores.
• Aumentar la seguridad y cumplimiento normativo. Resulta más sencillo aumentar las medidas de seguridad e incorporar las normativas necesarias con una base estandarizada sobre la que construir.

Creemos que es una iniciativa de la que estar pendiente ya que dará mucho que hablar y, por supuesto, una vez se libere una versión estable de la misma, incorporar a nuestro stack.

Referencias

• The API Future is Bright with the New API Workflows Specification
• Git Hub Arazzo-Specification
• Redefine API Testing with the OpenAPI workflows
• Post de David Roldán en Innovating API integrations with AI