Por qué los contratos de datos importan más que el código

Un contrato de datos es un acuerdo explícito entre el backend y el frontend sobre qué forma tienen los datos. No un documento Word. No un comentario en el código. Una especificación versionada que dice: este endpoint devuelve este objeto, con estos campos, de estos tipos, con estas restricciones.

Cuando ese acuerdo existe, el frontend puede desarrollarse en paralelo al backend usando datos mock que respetan el contrato. Cuando el backend está listo, la integración no tiene sorpresas. Cuando el contrato cambia, el cambio es explícito y rastreable.

Sin contrato, el frontend descubre el shape de los datos cuando ejecuta el código. Los bugs son a runtime, en producción, cuando un usuario toca la funcionalidad por primera vez.

La mayoría del software tiene contratos implícitos. El backend devuelve un objeto. El frontend lo usa. Con el tiempo, el frontend asume que ciertos campos siempre están presentes. El backend cambia un campo de nombre o de tipo. El frontend falla en runtime. Nadie lo sabe hasta que alguien lo reporta.

Los contratos implícitos no desaparecen cuando no los documentás. Solo se vuelven más difíciles de cambiar. Cada componente que consume un campo es una dependencia implícita de ese campo. Cambiar el campo requiere rastrear todos esos componentes manualmente.

En Pegasuz, el contrato de datos para el sitio institucional es el modelo de payload de contenido: un objeto con shape definido que incluye las páginas, las entidades (servicios, proyectos, blog), la configuración de traducción y la metadata de SEO.

El normalizeLegacySitePayload en cmsService.js es la implementación de ese contrato: transforma los datos crudos de la API en el objeto con la forma esperada por el frontend. Si la API cambia su formato, el cambio se absorbe en ese adaptador, no en los componentes.

Los componentes consumen el contrato, no la API. Si mañana cambiamos el backend de MySQL a PostgreSQL, o de REST a GraphQL, los componentes no se tocan.

El costo no es teórico. En una sesión anterior conectamos el sitio de Pegasuz al API y encontramos que cmsService.js esperaba { contents: [] } pero la API devuelve { tenant, items: [] }. El CMS retornaba array vacío siempre. Ese bug existió por semanas. El sitio parecía conectado. No lo estaba. Un contrato explícito lo hubiera capturado el primer día.

Un contrato útil especifica: los campos presentes y sus tipos, qué campos son opcionales y cuál es el valor por defecto cuando están ausentes, qué significa cada campo en términos del negocio, y qué variantes de formato puede tener un campo.

Los contratos que solo documentan el camino feliz son incompletos. Los casos edge — campos nulos, arrays vacíos, variantes de formato — son los que causan bugs en producción.

Definir un contrato bien tiene un costo upfront. Requiere pensar el modelo de datos antes de tenerlo implementado, consensuar con el equipo qué forma deben tener los datos, y mantener el contrato actualizado cuando el sistema evoluciona.

Ese costo se recupera en la primera integración que no requiere debugging. En el primer cambio de API que no rompe el frontend. En el primer desarrollador nuevo que puede entender la forma de los datos sin leer el código completo.

Los contratos no son documentación. Son restricciones que hacen el sistema más predecible. Y la predecibilidad, en software de larga vida, vale más que la velocidad inicial.