API First — Iniciación

Este curso está dirigido a desarrolladoras y desarrolladores que se incorporan por primera vez al paradigma API First y quieren entender cómo colocar el contrato de la API en el centro del proceso de desarrollo antes de escribir una sola línea de implementación. A lo largo de ocho horas, la persona participante descubrirá en qué se diferencia este enfoque del desarrollo tradicional, aprenderá a leer y navegar contratos OpenAPI reales, ejecutará peticiones HTTP siguiendo dichos contratos y detectará desviaciones entre la especificación y el comportamiento real de una API. Al finalizar el curso, será capaz de consumir una API guiándose exclusivamente por su contrato y de explicar cómo este artefacto vertebra la colaboración entre equipos de frontend, backend y QA desde el primer día del proyecto.

1. Explicar en qué consiste el paradigma API First y en qué dimensiones concretas se diferencia del enfoque de implementación primero.
2. Identificar los elementos estructurales de un contrato OpenAPI —rutas, métodos HTTP, parámetros, esquemas y códigos de estado— y reconocer la función de cada uno dentro de la especificación.
3. Clasificar correctamente parámetros de ruta, de consulta y de cuerpo a partir de ejemplos extraídos de contratos OpenAPI reales.
4. Seleccionar el código de estado HTTP adecuado para escenarios habituales del ciclo de vida de una API: creación de recurso, recurso no encontrado, error de validación y acceso no autorizado.
5. Ejecutar peticiones HTTP a una API usando Postman o cURL siguiendo con exactitud los parámetros y la estructura definidos en el contrato de referencia.
6. Detectar discrepancias entre la respuesta real de una API y su contrato OpenAPI, señalando el campo o comportamiento que no coincide.
7. Completar, de forma guiada, el código de una función cliente pre-estructurada rellenando la URL, el método y los parámetros correctos a partir de la lectura del contrato.
8. Describir el flujo de trabajo API First en un equipo de desarrollo, explicando cómo interactúan frontend, backend y QA a partir del contrato antes de que exista implementación.

Bloque 1 — El paradigma API First y su contexto (aprox. 1,5 h) Se introduce el paradigma API First comparándolo con el enfoque tradicional en el que la implementación precede al diseño del contrato. Se analizan al menos dos dimensiones que los distinguen: el orden de trabajo, el papel central del contrato como fuente de verdad y el impacto en la colaboración entre equipos. Se cierra el bloque describiendo cómo frontend, backend y QA pueden trabajar en paralelo desde el primer día del proyecto usando el contrato como punto de sincronización.

Bloque 2 — Anatomía de un contrato OpenAPI (aprox. 2 h) Se recorre la estructura de un documento OpenAPI real identificando sus secciones fundamentales: rutas, métodos HTTP, parámetros, esquemas de request y response, y códigos de estado. Se dedica atención especial a distinguir los tres tipos de parámetros —de ruta, de consulta y de cuerpo— mediante ejercicios de clasificación sobre ejemplos concretos. Se trabaja también el significado de los códigos de estado HTTP más habituales en el ciclo de vida de una API —creación exitosa, recurso no encontrado, error de validación y acceso no autorizado— a través de actividades de asociación.

Bloque 3 — Consumo de APIs siguiendo el contrato (aprox. 3 h) Se practica la ejecución de peticiones HTTP reales contra una API pública o de entorno guiado utilizando Postman y cURL, respetando fielmente los parámetros y la estructura especificados en el contrato OpenAPI de referencia. A continuación se ejercita la detección de discrepancias entre las respuestas obtenidas y lo que el contrato describe, identificando el campo o comportamiento exacto que difiere. El bloque culmina con una actividad de escritura guiada en la que se completa el código de una función cliente pre-estructurada (fetch/axios o equivalente) rellenando únicamente la URL, el método y los parámetros correctos leídos directamente del contrato.

Bloque 4 — Integración y revisión (aprox. 1,5 h) Se sintetiza el recorrido completo del flujo API First conectando todos los aprendizajes: desde la lectura del contrato hasta el consumo de la API y la validación de su comportamiento. Se resuelven dudas, se revisan los ejercicios prácticos realizados durante el curso y se propone un pequeño reto integrador en el que la persona participante aplica de forma autónoma los pasos del flujo sobre un contrato OpenAPI nuevo.

• Ordenador con conexión a internet estable.
• Postman instalado (versión de escritorio) o acceso a Postman Web.
• Terminal con cURL disponible (incluido por defecto en macOS y la mayoría de distribuciones Linux; en Windows se recomienda Git Bash, WSL o activar cURL desde PowerShell ≥ 7).
• Navegador web moderno (Chrome, Firefox, Edge o Safari en versión actualizada).
• Editor de texto o IDE con soporte de resaltado YAML/JSON (Visual Studio Code con la extensión «YAML» de Red Hat es suficiente).

• Conocimiento básico del protocolo HTTP: qué es una petición y una respuesta, y para qué sirven los métodos GET y POST.
• Familiaridad con el formato JSON: saber leer y escribir objetos y arrays sencillos.
• Haber ejecutado al menos una vez un comando en la terminal o haber enviado una petición con alguna herramienta similar a Postman, aunque sea en un contexto diferente.