Desarrollo Backend y APIs · BAC-192

Diseño de APIs: contratos, versiones y OpenAPI

Especificación primero con OpenAPI: contratos, generación de clientes y evolución sin romper consumidores

Bajo demanda Avanzado 7 módulos · 31 clases

Formato asíncrono Desarrollo, Ingeniería / Industria OpenAPI

DESARROLLO

Lo que aprenderás

Escribir una especificación OpenAPI completa con rutas, esquemas, respuestas y ejemplos reutilizables
Aplicar el enfoque de especificación primero validando el contrato antes de escribir código
Generar clientes y esqueletos de servidor a partir del documento y mantenerlos sincronizados
Distinguir cambios compatibles de cambios que rompen y aplicar una política de versiones
Modelar errores de forma uniforme con Problem Details y códigos de negocio estables
Validar peticiones y respuestas contra el esquema en pruebas de contrato automatizadas
Publicar y gobernar la especificación con reglas de estilo verificadas por linter

Contenido del curso

7 módulos · 31 clases en vídeo · práctica guiada en cada módulo

Módulo 1 · Presentación y enfoque 4 clases

Documentar después frente a especificar primero
Qué es OpenAPI y qué no resuelve
Herramientas del curso y editor de especificaciones
El servicio que se especificará durante el curso

Módulo 2 · Anatomía de una especificación 5 clases

Información, servidores y rutas
Operaciones, parámetros y cuerpos de petición
Respuestas, códigos de estado y cabeceras
Esquemas y componentes reutilizables
Ejemplos que sirven de documentación viva

Módulo 3 · Modelado del contrato 5 clases

Nombrar recursos y operaciones con coherencia
Tipos, formatos, valores nulos y opcionalidad
Composición de esquemas y polimorfismo
Paginación, filtrado y ordenación en el contrato
Autenticación declarada en la especificación

Módulo 4 · Errores 4 clases

Formato uniforme de error con Problem Details
Códigos de negocio estables frente a mensajes
Errores de validación campo a campo
Documentar los fallos previsibles de cada operación

Módulo 5 · Generación y sincronización 4 clases

Generar clientes en varios lenguajes
Generar el esqueleto del servidor
Servidores simulados para desbloquear al equipo cliente
Mantener código y especificación sincronizados

Módulo 6 · Validación y pruebas de contrato 4 clases

Linter de especificaciones y reglas de estilo
Validar peticiones y respuestas contra el esquema
Pruebas de contrato en la canalización
Detectar cambios que rompen antes de publicar

Módulo 7 · Evolución y gobierno 5 clases

Cambios compatibles y cambios que rompen
Estrategias de versión y su coste
Depreciación con plazos y comunicación a consumidores
Portal de documentación y catálogo de APIs
Caso práctico: especificar, generar y evolucionar un servicio

Requisitos

Experiencia diseñando o consumiendo APIs REST en proyectos reales
Conocer HTTP, JSON y los códigos de estado con soltura
Manejo de Git y de canalizaciones de integración continua para automatizar validaciones

Descripción

La mayoría de las APIs se documentan después, cuando el código ya decidió por nosotros los nombres, los formatos de fecha y qué se devuelve al fallar. El resultado es una documentación que va por detrás, clientes que descubren cambios en producción y equipos que no pueden trabajar en paralelo porque nadie sabe qué va a devolver el servicio hasta que existe.

Este curso invierte ese orden. Se escribe primero la especificación OpenAPI del servicio, con esquemas reutilizables, ejemplos y errores modelados, y se valida con un linter que impone reglas de estilo comunes. A partir de ella se generan cliente y esqueleto de servidor, y se montan pruebas de contrato que comprueban que la implementación real cumple lo declarado.

La parte final aborda la evolución: qué cambios se pueden hacer sin avisar, cuáles exigen una versión nueva y cómo retirar una antigua con plazos. Es aplicable a equipos de desarrollo que publican APIs a terceros y a ingeniería que integra sistemas de distintos proveedores y necesita un contrato verificable entre ellos.

¿Para quién es este curso?

Equipos que publican APIs consumidas por otros departamentos o por clientes externos
Perfiles de ingeniería que integran equipos y sistemas de proveedores distintos
Responsables técnicos que quieren imponer un estilo común a las APIs de la organización