Diferencias entre contrato y comportamiento real

La diferencia entre lo que el contrato promete y lo que la API hace se suele llamar deriva. Aparece por caminos muy normales: un desarrollador agrega una ruta para un informe urgente, un framework expone por defecto un método que nadie pidió, una consulta a la base de datos devuelve todas las columnas y el serializador las pasa todas a la respuesta. Ninguno de esos cambios toca el contrato, así que la revisión de diseño, la documentación y las pruebas generadas a partir de él siguen diciendo que todo está bien.

Por eso la deriva no se busca releyendo el contrato. Se busca comparándolo con algo que muestre lo que la API hizo de verdad: el registro de la pasarela o del servicio, que dice qué combinaciones de método y ruta respondieron con éxito, y respuestas reales guardadas con una cuenta de prueba, que dicen qué campos salieron.

Abre el laboratorio. En recetas-v1.yaml hay tres rutas, cada una con sus métodos. Las rutas del contrato tienen plantillas ({recetaId}) y en el registro aparecen con valores concretos, así que compara la forma, no el texto exacto. Recorre registro-pasarela.txt y separa lo que encaja en alguna ruta del contrato de lo que no encaja en ninguna, con ningún método.

No todo lo que no está en el contrato se nota igual. Una ruta inventada es fácil de ver; un método de más sobre una ruta que sí existe pasa desapercibido, porque la ruta parece conocida. Y no todo intento fuera del contrato es un problema: si la API lo rechazó con un 404, un 405 o un 403, la puerta estaba cerrada.

Cuenta en el registro las peticiones cuya combinación de método y ruta no está en el contrato y que aun así recibieron una respuesta de éxito (cualquier estado 2xx).

La deriva también vive dentro de las respuestas. Un esquema de respuesta es una promesa de qué sale; si la respuesta real trae más, ese dato sale sin que nadie haya decidido que salga, y es justo el caso que el Top 10 de OWASP para APIs (edición 2023) agrupa en la autorización a nivel de propiedad (API3:2023): el cliente recibe propiedades que no debería ver.

Compara respuesta-receta.json con el esquema Receta del contrato, propiedad por propiedad. Hay dos campos de más; uno es ruido técnico y el otro no.

Arreglar las tres diferencias de hoy no impide las de mañana. La deriva se controla cuando el contrato deja de ser un documento que se actualiza a mano y pasa a ser la regla que algo comprueba en cada cambio y en cada petición. Cada diferencia encontrada exige además una decisión: o la API se ajusta al contrato, o el contrato se cambia con revisión de seguridad para incluir lo que de verdad hace falta.