Un cambio de campo en una API puede parecer inocuo para quien produce el dato y romper un dashboard semanas después. Los consumidores analíticos dependen del significado, los nulos, las unidades y los plazos de entrega, aspectos invisibles en un ejemplo JSON. Un contrato explicita esas expectativas y ayuda a evolucionarlas con seguridad.
Un contrato útil incluye nombre, tipo, obligatoriedad, semántica de nulos, unidad, valores admitidos, responsable, sensibilidad, frescura y política de compatibilidad. En eventos, añade identidad, orden y posibilidad de duplicados. En APIs, documenta peticiones, respuestas, errores y paginación además de la estructura.
| Cambio | Pregunta estructural | Pregunta de negocio |
|---|---|---|
| Añadir campo opcional | ¿Los lectores antiguos pueden ignorarlo? | ¿Los modelos dejan de ver una dimensión importante? |
| Renombrar o eliminar | ¿Los consumidores antiguos aún procesan el payload? | ¿Qué informes dependen del significado anterior? |
| Número a texto | ¿El validador acepta el nuevo esquema? | ¿Ordenación, agregación y unidad siguen correctas? |
| Cambiar valores enum | ¿Se admiten valores desconocidos? | ¿Los paneles clasifican bien los nuevos estados? |
| Cambiar el timestamp | ¿Sigue siendo una fecha válida? | ¿Cambió el huso o el significado de evento frente a proceso? |
La compatibilidad hacia atrás ayuda, pero las reglas concretas varían entre JSON Schema, Avro, Protobuf y la configuración del registry. Un cambio válido estructuralmente aún puede alterar el sentido de negocio. Mantén definiciones semánticas y ejemplos junto al esquema y prueba tanto la validación como los modelos consumidores.
Versiona los contratos en el repositorio, asigna un responsable al productor y enumera los consumidores críticos. Los pull requests deberían ejecutar validación, comprobaciones de compatibilidad y pruebas analíticas representativas. Un cambio incompatible debe identificar consumidores afectados, dar plazo de migración y, si es posible, publicar una versión nueva antes de retirar la anterior.
Conserva registros originales con hora de ingesta y versión del esquema para repetir transformaciones corregidas. No conviertas silenciosamente valores inválidos en cero o cadena vacía: envíalos a cuarentena con recuentos y muestras sin datos sensibles.
Mide fallos de validación, campos o enums desconocidos, cambios en nulos, retraso de frescura, variación del volumen y errores de los modelos consumidores. Vincula las alertas al dataset y su responsable. Conserva la lineage desde la API o el topic hasta la métrica. Si cambia un indicador, el equipo debería identificar versión del contrato y ventana de origen.
El productor responde por el significado de origen y el aviso de cambios; analytics, por las transformaciones y definiciones; la plataforma, por validación, almacenamiento y entrega. Los contratos funcionan con responsables asignados y revisión, no como archivos sin cumplimiento.
Relacionado: pasar informes de Sheets a SQL e informes operativos con APIs, ETL y SQL.
El contrato conecta la API productora con las decisiones analíticas. Versiona expectativas estructurales y semánticas, valida compatibilidad en CI, conserva datos brutos reproducibles y vigila calidad y frescura mediante lineage. Así, un cambio de esquema se convierte en migración revisada y no en una sorpresa del dashboard.