Un equipo crea una aplicación esperando que el campo total sea numérico. El backend devuelve texto formateado. Un colaborador interpreta la fecha en otro huso horario. Todos han implementado algo razonable, pero la integración falla cuando las piezas se encuentran.
En el desarrollo API contract-first, el contrato se define antes de implementar. Una descripción OpenAPI registra operaciones, parámetros, autenticación, esquemas, errores y ejemplos en un formato comprensible para personas y herramientas. La misma fuente alimenta documentación, mocks, SDK y pruebas.
El enfoque cobra importancia con software creado mediante IA y agentes que consumen herramientas. En 2026, Swagger añadió compatibilidad con OpenAPI 3.2 y amplió la detección de drift; el 21 de octubre, HPE anunció API gobernadas para integrar servicios de IA en aplicaciones. Cuanto más rápido se produce código, más necesario es un contrato verificable.
Code-first y contract-first
En code-first, la implementación nace primero y la documentación se extrae después. Puede funcionar cuando un solo equipo controla cliente y servidor y el dominio cambia rápidamente. El riesgo es publicar documentación tarde, incompleta o demasiado vinculada a detalles internos.
En contract-first, consumidores, seguridad y negocio revisan la interfaz antes de que exista el servidor. Backend y clientes trabajan en paralelo con mocks. El contrato no sustituye al código; establece el comportamiento observable que todas las implementaciones respetan.
Qué debe definir un contrato OpenAPI
- operaciones, rutas y métodos HTTP;
- parámetros, cabeceras y cuerpo de la solicitud;
- tipos, formatos, campos obligatorios y validaciones;
- respuestas de éxito y error;
- autenticación y ámbitos de autorización;
- paginación, filtros, orden y límites;
- ejemplos realistas sin datos sensibles;
- versiones, estabilidad y retirada prevista.
Una lista de endpoints no basta. Los errores también forman parte de la API. El consumidor necesita saber si debe corregir datos, renovar un token, reintentar o abrir una excepción.
Flujo contract-first en la práctica
1. Diseñar la experiencia del consumidor
Empiece por el caso de uso. ¿Qué necesita la app para completar una pantalla? ¿Qué acción debe realizar el ERP? Evite exponer directamente la estructura de la base; la API representa capacidades del negocio.
2. Modelar contrato y ejemplos
Defina nombres, formatos, límites y errores coherentes. Los ejemplos permiten validar significado con perfiles no técnicos. El contrato pasa por lint para comprobar seguridad, estilo y compatibilidad.
3. Publicar un mock
Un servidor simulado responde conforme al contrato antes de terminar el backend. Aplicación, portal y colaboradores comienzan a integrar y encuentran carencias cuando cambiar la interfaz aún es barato.
4. Generar artefactos
Las herramientas producen tipos, clientes, stubs y documentación. El código generado evita trabajo repetitivo, pero no sustituye las decisiones de arquitectura ni las reglas empresariales.
5. Implementar y verificar conformidad
Las pruebas comprueban que las respuestas reales coinciden con la especificación. Los cambios incompatibles se bloquean en el pull request. Las pruebas del consumidor verifican que sus escenarios siguen disponibles.
Ejemplo: app conectada al sistema de pedidos
Una empresa quiere consultar pedidos y solicitar anulaciones desde una app. Producto, móvil y backend acuerdan la lista, estados, paginación y respuesta de anulación. También especifican pedido enviado, plazo vencido, usuario sin permiso y servicio no disponible.
El equipo móvil desarrolla contra el mock y genera modelos tipados. Backend implementa las mismas estructuras. Si intenta renombrar shippingStatus, la comparación detecta la ruptura antes del despliegue. Un nuevo campo opcional puede evolucionar de forma compatible.
Además de reducir errores, los equipos trabajan en paralelo y preproducción deja de ser el primer punto de encuentro entre cliente y servidor.
Versionar sin romper consumidores
Los cambios aditivos suelen ser seguros: un campo opcional, un endpoint nuevo o un valor con fallback. Eliminar propiedades, hacerlas obligatorias o cambiar su tipo puede romper aplicaciones no actualizadas.
Utilice análisis de compatibilidad en CI y una política de retirada. Registre consumidores, comunique fechas y observe el uso antes de eliminar una versión. Versionar cada pequeño cambio fragmenta; romper en silencio es peor.
Pruebas de contrato y detección de drift
Hay drift cuando especificación e implementación se separan por cambios manuales, documentación obsoleta o diferencias entre entornos. Las pruebas deben validar respuestas, estados, cabeceras y autenticación en preproducción y de forma controlada en producción.
El proveedor demuestra que cumple la especificación. El consumidor registra las interacciones de las que depende. Juntos evitan una API inválida y la eliminación de un comportamiento esencial que no parecía importante en el contrato genérico.
Seguridad dentro del contrato
- definir autenticación y ámbitos por operación;
- no publicar ejemplos con tokens o información real;
- limitar tamaño, formato y contenido de entrada;
- normalizar errores sin revelar detalles internos;
- marcar datos personales y aplicar minimización;
- separar operaciones administrativas;
- validar autorización en servidor, no solo en interfaz.
OpenAPI describe la seguridad esperada, pero no garantiza su implementación. Pruebas y revisión deben comprobar el comportamiento real.
API para personas, aplicaciones y agentes
Los agentes de IA también necesitan entender herramientas, parámetros y respuestas. Un contrato claro facilita clientes y adaptadores, pero la descripción entregada al agente debe limitarse a las operaciones necesarias. No exponga una API administrativa completa si la automatización solo consulta estados.
OpenAPI y MCP pueden complementarse. OpenAPI describe la interfaz HTTP; MCP organiza el descubrimiento y uso de herramientas por modelos. La gobernanza permanece en la API: identidad, alcance, validación, idempotencia y auditoría.
Cuándo puede ser excesivo
Un prototipo interno desechable quizá no necesite un proceso completo. Una integración sencilla controlada por una persona puede comenzar code-first. Contract-first suele compensar con equipos independientes, aplicaciones móviles, colaboradores, API públicas o varios consumidores.
El objetivo no es producir un YAML perfecto, sino reducir decisiones implícitas. Un contrato pequeño, revisado y probado vale más que una especificación enorme que nadie mantiene.
Métricas del proceso
- errores encontrados antes de preproducción;
- tiempo hasta el primer cliente funcional;
- cambios incompatibles bloqueados en CI;
- diferencias entre documentación y producción;
- tiempo dedicado a dudas de consumidores;
- operaciones con ejemplos y errores definidos;
- uso y retirada por versión.
Adoptarlo en un proyecto existente
- empezar por la API más utilizada o problemática;
- extraer la descripción y confirmar el comportamiento real;
- corregir divergencias sin romper consumidores;
- definir reglas de nombres, errores, paginación y seguridad;
- publicar documentación y mock controlados;
- añadir lint, comparación y pruebas a CI/CD;
- revisar el contrato antes de cambios públicos.
Integraciones que evolucionan con previsibilidad
Una API es una promesa entre sistemas. Si solo existe en conversaciones y código, cada equipo crea su propia versión. Contract-first vuelve el acuerdo visible, ejecutable y comprobable, reduciendo retrabajo y acelerando aplicaciones, colaboradores y automatizaciones.
ProativaIA desarrolla software a medida, aplicaciones y automatizaciones integradas. Podemos diseñar o modernizar su API y crear contratos OpenAPI, mocks, SDK y pruebas para conectar sistemas con seguridad y previsibilidad.