¿Qué es un contrato de datos entre frontend y backend?
Un contrato de datos es un acuerdo sobre la forma en que dos partes de un sistema intercambian información. En una aplicación web define qué puede enviar el cliente, qué responde el servidor y qué significa cada campo.
El contrato puede expresarse mediante documentación de una API, un esquema, ejemplos de solicitudes y respuestas o especificaciones formales. Lo importante es que ambos lados compartan las mismas expectativas.
¿Qué define un contrato de datos?
Un contrato puede definir nombres de campos, tipos de datos, valores obligatorios, identificadores, operaciones permitidas, estructuras de respuesta y condiciones de error.
Por ejemplo, una actualización puede requerir el identificador de un registro, la versión que conoce el cliente y los campos que el usuario desea modificar. El servidor puede entonces determinar si esa operación continúa siendo válida.
Un contrato claro reduce suposiciones. El frontend no necesita adivinar si un valor ausente significa cero, una cadena vacía, un campo no disponible o un error.
La identidad y la propiedad forman parte del modelo
Cuando la información puede modificarse, el sistema necesita saber qué registro está cambiando y, cuando corresponde, quién tiene permitido modificarlo.
Un identificador distingue un registro de otro. La propiedad, los roles o los permisos pueden establecer quién tiene autoridad sobre una operación. Estas reglas deben ser validadas por el servidor aunque la interfaz también las utilice para decidir qué controles mostrar.
Las versiones ayudan a manejar cambios concurrentes
Fechas como created_at y updated_at proporcionan información útil sobre cuándo se creó o modificó un registro. Para algunos flujos, un número de versión puede aportar un mecanismo adicional para controlar actualizaciones concurrentes.
Si un cliente lee la versión 8 y después intenta actualizar esa misma versión, el servidor puede rechazar la operación cuando el registro almacenado ya avanzó a la versión 9. Esto evita que una solicitud posterior sobrescriba silenciosamente un cambio que el cliente nunca conoció.
Las operaciones repetidas también necesitan reglas
Una conexión puede fallar después de que el servidor recibió una solicitud pero antes de que el cliente reciba la respuesta. Si el cliente envía nuevamente la misma operación, el servidor necesita una forma de determinar si debe procesarla dos veces.
Un identificador de operación u otra estrategia de idempotencia puede ayudar a reconocer solicitudes repetidas. El mecanismo exacto depende del proceso de negocio, pero la responsabilidad pertenece al contrato y al comportamiento del servidor, no a un estado visual de la interfaz.
Un estado de interfaz no es el contrato
Etiquetas como pendiente, sincronizado, rechazado o conflicto pueden ser útiles para informar al usuario. Sin embargo, esos estados solamente tienen significado cuando están respaldados por reglas reales.
Un conflicto no se resuelve porque el frontend almacene una variable llamada conflicto. El sistema debe saber qué versiones participan, qué operación se intentó y qué autoridad decide lo que puede ocurrir después.
La interfaz representa el resultado de esas reglas. No las sustituye.
¿Por qué importa el contrato en web, móvil y trabajo sin conexión?
Un contrato bien definido separa las reglas de los datos de la tecnología utilizada por el cliente. El mismo backend puede comunicarse con un sitio web, una aplicación JavaScript, un cliente Android, una aplicación iOS o una interfaz de navegador capaz de trabajar temporalmente sin conexión.
Si todos los clientes respetan las mismas reglas de identificadores, versiones, permisos y operaciones, el sistema puede conservar un comportamiento consistente sin depender de un framework de frontend particular.
El contrato de datos define qué significa una operación; la interfaz solamente representa su resultado actual ante el usuario.
Diseñar ese acuerdo antes de agregar estados de interfaz facilita identificar responsabilidades, manejar errores y hacer evolucionar diferentes clientes sin trasladar las reglas de negocio a cada pantalla.