API First — Intermedio

Este curso está dirigido a desarrolladores y arquitectos de software que ya conocen los fundamentos del paradigma API First y quieren consolidar su práctica en entornos de proyecto reales. A lo largo de las ocho horas de formación, los participantes profundizarán en el diseño de contratos OpenAPI 3.x para dominios funcionales completos, aprenderán a gestionar el versionado y la retrocompatibilidad ante cambios de requisitos, incorporarán servidores de mock y reglas de linting automatizado en flujos de trabajo de equipo, y desarrollarán criterio para modelar recursos, relaciones y esquemas de error de forma coherente y justificada. Al finalizar, cada participante será capaz de entregar un contrato OpenAPI producción-ready, conectado a un pipeline de integración continua, que un equipo consumidor pueda utilizar de forma autónoma antes de que exista una sola línea de implementación.

1. Comparar el enfoque API First frente al enfoque Code First en escenarios concretos de proyecto, argumentando las ventajas, los riesgos y las condiciones en las que cada uno resulta más adecuado.
2. Diseñar un contrato OpenAPI 3.x completo para un dominio funcional acotado con un mínimo de tres recursos relacionados, definiendo rutas, métodos, códigos de estado y esquemas de datos antes de producir ningún código de implementación, e incluyendo esquemas de error reutilizables que diferencien con claridad los errores de cliente (4xx) de los de servidor (5xx).
3. Justificar la estructura de recursos y sus relaciones en el contrato diseñado, eligiendo de forma razonada entre recursos anidados, referencias por ID o recursos independientes según el contexto.
4. Integrar un servidor de mock generado a partir del contrato OpenAPI en el flujo de trabajo del equipo, de modo que un consumidor pueda operar contra dicho mock sin acceso a la implementación real, e incorporar reglas de linting de contrato en un pipeline de CI básico que bloquee el avance ante incumplimientos.
5. Depurar discrepancias entre un contrato OpenAPI dado y su implementación real —campo ausente, tipo incorrecto y código de estado inesperado, entre otros— y proponer la corrección en el artefacto adecuado, ya sea el contrato o el código.
6. Adaptar un contrato API existente ante un cambio de requisito funcional manteniendo retrocompatibilidad básica y justificando las decisiones de diseño tomadas.

Bloque 1 — API First vs. Code First: criterio de decisión. Se revisan los principios que distinguen ambos enfoques y se analizan escenarios concretos de proyecto para argumentar cuándo cada estrategia aporta mayor valor, cuáles son sus riesgos inherentes y qué condiciones organizativas o técnicas inclinan la balanza en uno u otro sentido.

Bloque 2 — Diseño de contratos OpenAPI 3.x para dominios complejos. Los participantes diseñan desde cero un contrato para un dominio funcional con varios recursos interrelacionados, definiendo rutas, verbos HTTP, parámetros, códigos de estado y esquemas de datos. Se presta especial atención al modelado de relaciones entre recursos —anidamiento, referencia por ID o recurso independiente— y a la justificación explícita de cada decisión de diseño.

Bloque 3 — Esquemas de error consistentes y reutilizables. Se establece una estrategia uniforme para la gestión de errores en el contrato: diferenciación entre errores 4xx y 5xx, definición de estructuras de error canónicas mediante $ref, y criterios para asignar códigos de estado de forma coherente a lo largo de todo el API.

Bloque 4 — Mocks y automatización en el flujo de equipo. Se integra un servidor de mock generado directamente desde el contrato OpenAPI para que los equipos consumidores puedan desarrollar e iterar sin depender de la implementación real. A continuación se configura un ruleset personalizado de Spectral y se conecta al pipeline de CI, de forma que cualquier contrato que incumpla las reglas definidas bloquee el avance de la pipeline.

Bloque 5 — Mantenimiento y evolución del contrato. Se aborda cómo detectar y corregir desviaciones entre el contrato y la implementación —campos ausentes, tipos incorrectos, códigos de estado inesperados— y cómo adaptar un contrato ante nuevos requisitos funcionales preservando la retrocompatibilidad básica y documentando las decisiones tomadas (campo opcional frente a nuevo endpoint, estrategia de versión, etc.).

• Acceso a un entorno con Node.js ≥ 18 instalado para ejecutar herramientas como Spectral y Prism (servidor de mock de Stoplight).
• Editor de código con soporte YAML y extensión OpenAPI (se recomienda Visual Studio Code con la extensión Swagger Viewer o OpenAPI Editor).
• Cuenta en una plataforma de CI accesible (GitHub Actions, GitLab CI o equivalente) con permisos para crear o modificar workflows en un repositorio de pruebas.
• Conexión a internet para descargar dependencias npm y acceder a la documentación oficial de OpenAPI 3.x.

• Conocimiento de los fundamentos de HTTP (verbos, códigos de estado, cabeceras) y de la estructura básica de un documento OpenAPI (paths, components, schemas).
• Experiencia mínima en la escritura o lectura de un contrato OpenAPI 3.x, cubierta en el curso APF01.
• Familiaridad con el concepto de pipeline de integración continua (CI) y capacidad para ejecutar comandos básicos en terminal.
• Nociones de versionado semántico y de trabajo colaborativo con un repositorio de control de versiones (Git).