Arazzo Especificaciones: Guía Práctica para Flujos de Trabajo de Diseño de APIs

La especificación Arazzo es un estándar de la Iniciativa OpenAPI que describe los flujos de trabajo de API —pasos ordenados que llaman a una o más API para lograr un objetivo. Mientras que una única especificación OpenAPI se centra en una única superficie de API (rutas, operaciones, esquemas, seguridad), una descripción Arazzo captura la coreografía en torno a esas API: las entradas que cada paso necesita, las dependencias entre los pasos, los criterios de éxito que marcan el progreso y las salidas que se deben pasar. En resumen, Arazzo es una forma formal y legible por máquina de modelar escenarios de "haz esto, luego aquello" que los desarrolladores ya construyen en código y los probadores ya automatizan en suites.

En la práctica, la mayoría de los equipos ya lidian con flujos de trabajo:

• Iniciar sesión, luego obtener perfil, luego actualizar preferencias
• Crear carrito, añadir artículos, calcular totales, pagar y confirmar
• Enviar solicitud, consultar estado, subir documentos, recibir aprobación

Arazzo proporciona un lenguaje compartido para estas secuencias. El formato es JSON o YAML. Un objeto de nivel superior declara la versión de Arazzo (arazzo: 1.0.x), metadatos (info), una lista de descripciones de API de origen (sourceDescriptions, a menudo archivos de especificación OpenAPI que ya mantiene), una lista de flujos de trabajo (workflows) y piezas reutilizables en components. Cada flujo de trabajo contiene inputs (nombres y tipos), steps ordenados (con IDs de paso), parameters opcionales inyectados en las llamadas a la API referenciadas, successCriteria (aserciones simples como $statusCode == 200) y outputs que los pasos posteriores pueden consumir.

¿Por qué esto es importante para el diseño y la especificación de API?

• Reduce las conjeturas. Muestra cómo se debe usar la API, no solo lo que hace cada punto final de forma aislada.
• Mejora los traspasos. Producto, backend, frontend y QA leen la misma descripción breve del flujo de trabajo.
• Habilita herramientas. Dado que Arazzo es legible por máquina, los editores, linters, mockers y ejecutores pueden usarlo.
• Soporta cambios. Si un punto final evoluciona, el flujo de trabajo mantiene a los consumidores alineados con la ruta feliz.

Arazzo no reemplaza la especificación OpenAPI. Más bien, añade una capa adicional. Arazzo apunta a uno o más documentos OpenAPI (a través de sourceDescriptions) y los compone en flujos de extremo a extremo. Mantener estos roles distintos ayuda a tener claridad: OpenAPI describe la API; Arazzo describe cómo usar una o más API para realizar un trabajo.

Dentro del Objeto de Especificación Arazzo

Un recorrido rápido y guiado le ayudará a leer y crear archivos Arazzo con confianza. Las secciones principales que verá son:

• arazzo: Versión de Arazzo, por ejemplo 1.0.1.
• info: Título, resumen, descripción y versión de la descripción del flujo de trabajo.
• sourceDescriptions: Una lista de especificaciones de origen utilizadas en los flujos de trabajo. Cada entrada tiene name, type (por ejemplo, openapi) y una url al origen, como una especificación OpenAPI publicada.
• workflows: Un array de objetos de flujo de trabajo. Cada uno contiene workflowId, summary, description, inputs, steps y outputs a nivel de flujo de trabajo.
• components: Esquemas reutilizables utilizados en la descripción del flujo de trabajo.

Un paso típico contiene:

• stepId: Una etiqueta única, como loginStep o getPetStep.
• Una referencia a una operación de API por operationId u operationPath que apunta a una especificación OpenAPI de origen.
• parameters: Valores inyectados en la solicitud, a menudo tomados de inputs o outputs de pasos anteriores.
• successCriteria: Verificaciones booleanas simples como $statusCode == 200.
• outputs: Variables capturadas de encabezados o del cuerpo, por ejemplo, tokenExpires: $response.header.X-Expires-After o sessionToken: $response.body.

Para dejar clara la división del trabajo, utilice el siguiente modelo mental:

Cómo la Especificación Arazzo Complementa la Especificación OpenAPI

Arazzo y OpenAPI se alinean bien en el diseño de API. OpenAPI sigue siendo su contrato de registro para un servicio. Arazzo se convierte en su guía de procedimientos sobre cómo encadenar servicios. Cuando publica ambos, los consumidores entienden el porqué y el cómo:

• Por qué existe cada punto final en el contexto de un viaje de negocio
• Cómo llamarlos en orden, qué pasar y qué esperar de vuelta

Buenas prácticas:

• Mantenga sourceDescriptions apuntando a URLs de especificaciones OpenAPI estables y versionadas
• Nombre workflowId y stepId claramente; trátelos como código que buscará más tarde
• Mantenga las aserciones simples y obvias; úselas como criterios de aceptación vivos
• Capture solo las salidas que usará. Cuanto más corto, más fácil de mantener

Ejemplos que Fundamentan la Especificación Arazzo en Escenarios Reales de Diseño de API

Anclemos la idea con tres flujos comunes. Lo mantendremos simple y evitaremos cargas útiles gigantes, pero aún así mostraremos el valor de Arazzo.

1. Inicio de sesión de usuario + listar elementos disponibles

• Entradas: username, password
• Pasos: loginUser (éxito cuando $statusCode == 200), luego getItems con una consulta status=available y encabezado Authorization: $steps.loginUser.outputs.sessionToken
• Salidas: availableItems del $response.body

2. Pago y captura de pago

• Entradas: cartId, paymentMethod
• Pasos: getCartTotals → createPaymentIntent → confirmPayment
• Pasar totales y un secreto de cliente entre pasos
• Aserciones en cada paso ($statusCode == 200 y una verificación de campo como $.status == "confirmed")

3. Envío y consulta de estado de la aplicación

• Entradas: appPayload
• Pasos: submitApplication → pollStatus se repite hasta que $.state in ["APPROVED","REJECTED"]
• Salidas: decision y reason

En una descripción de Arazzo, esto se lee como un guion corto. Ingenieros, QA, redactores técnicos y socios pueden escanearlos rápidamente. Algunos consejos prácticos al crear ejemplos:

• Prefiera operationId cuando controle la especificación OpenAPI; es estable ante cambios de ruta
• Use operationPath cuando deba señalar una ruta específica en una OpenAPI de terceros
• Mantenga las inputs tipadas y documentadas (cadena, número, objeto) para generar mejores formularios e interfaces de usuario más tarde
• Recopile solo las salidas que necesite; evite convertir el flujo de trabajo en un segundo modelo de datos
• Agregue un summary de una línea para cada paso como si estuviera escribiendo un mensaje de commit

Cómo esto ayuda a que el diseño y la especificación de API trabajen juntos:

• Los diseñadores de API piensan en viajes y casos extremos; Arazzo los captura en pasos claros
• Los desarrolladores obtienen una lista de verificación de aceptación lista para usar; reduce las idas y venidas
• Los probadores derivan pruebas de escenario directamente del flujo de trabajo; sin reinterpretación

Finalmente, dado que Arazzo es legible por máquina, puede construir pequeñas utilidades para renderizar flujos de trabajo en documentos legibles por humanos, verificaciones de CI o diagramas, y puede mantenerlos cerca de su repositorio de especificaciones OpenAPI.

Uso de Apidog para Operacionalizar el Diseño de API: Especificación OpenAPI + Flujos de Trabajo Alineados con Arazzo

Arazzo explica el flujo de trabajo. OpenAPI explica la API. Apidog le ayuda a convertir ambos en un producto funcional con menos esfuerzo. Si bien Arazzo no es un formato de autoría dentro de Apidog hoy, la plataforma se alinea naturalmente con sus ideas y le brinda las herramientas diarias para diseñar, probar y publicar API en las que los consumidores confían.

Diseñe y modele con confianza:

• Diseño visual de API para rutas, operaciones, esquemas, seguridad y ejemplos
• Gestión por lotes para puntos finales, parámetros globales y componentes reutilizables
• Asistencia de IA integrada y una verificación de cumplimiento de puntos finales impulsada por IA para calificar la calidad de la documentación según las directrices de diseño de API de su equipo

Desarrolle y depure más rápido:

• Ejecutor de solicitudes rico con entornos, variables e historial
• Casos de punto final (pruebas de escenario) que reflejan flujos basados en pasos: extraer variables (JSONPath), encadenar solicitudes y afirmar el éxito
• Pruebas basadas en datos y de rendimiento para detectar regresiones tempranamente

Publique documentación que las personas y las IA puedan usar:

• Documentación interactiva en vivo que se mantiene sincronizada con su especificación OpenAPI
• Cinco modos de acceso: Público, Contraseña, Lista de permitidos por IP, Lista de permitidos por correo electrónico y Inicio de sesión personalizado
• Características compatibles con LLM: publicar Markdown para cada página, generar llms.txt, habilitar MCP para guiar agentes IDE como Cursor o Cline

Distribuya y aprenda:

• Publique API públicas en API Hub para su descubrimiento
• Utilice análisis y bucles de retroalimentación para refinar ejemplos, descripciones y cobertura de pruebas

Arazzo le brinda flujos de trabajo claros. Apidog le brinda la plataforma para dar forma, probar y presentar su API en torno a esos flujos de trabajo. El resultado es un mejor diseño de API, una especificación de API más sólida y una adopción más rápida.

Conclusión

La especificación Arazzo añade un contexto que faltaba a los programas de API: documenta flujos de trabajo reales de una manera concisa y legible por máquina. Los equipos no tienen que adivinar el orden de las llamadas, las entradas o las señales de éxito. Combine eso con la especificación OpenAPI, y ahora posee tanto el contrato como la guía de procedimientos. Las partes interesadas comprenden la intención, y las herramientas pueden automatizar el camino desde la idea hasta el software en funcionamiento.

Para convertir esos documentos en software fiable, adopte una plataforma que operacionalice los buenos hábitos de diseño de API. Apidog proporciona un espacio de trabajo unificado para modelar puntos finales, reutilizar componentes, ejecutar pruebas de escenario y publicar documentación con un fuerte control de acceso y salidas compatibles con LLM. Características como la verificación de cumplimiento de puntos finales impulsada por IA, los casos de punto final y las opciones de publicación (páginas Markdown, llms.txt, MCP) ayudan a que su API se mantenga consistente, clara y fácil de integrar.

Si ya gestiona una especificación OpenAPI, considere añadir una descripción Arazzo junto a ella para capturar sus flujos más importantes. Luego, importe la especificación a Apidog, cree pruebas que reflejen los pasos del flujo de trabajo y publique documentos que ayuden tanto a las personas como a los asistentes de IA a tener éxito. Esta combinación reduce la reelaboración, acelera la entrega y aumenta la confianza en todo su ciclo de vida de API, desde el diseño de API hasta la especificación de API y la adopción. ¿Listo para ir más allá? Regístrese en Apidog y déle a su equipo las herramientas para entregar grandes API con menos fricción.