Mock de API de contrato primero

Por qué empezar con un contrato

Desarrollé MockDeck después de ver a equipos desperdiciar semanas esperando a que llegara un backend que nunca llegaba a tiempo. El primer paso que doy con cualquier nueva característica es escribir una breve descripción del endpoint que tanto los ingenieros frontend como backend pueden revisar. Esa descripción se convierte en el contrato. Cuando el contrato está fijo, el frontend puede empezar a codificar contra un mock que se comporta exactamente como el servicio real, mientras que el equipo de backend trabaja en la implementación en paralelo. Esto elimina el período de inactividad en el que los desarrolladores se quedan mirando un 404 o un placeholder que solo devuelve códigos de éxito. Al anclar el trabajo a un artefacto concreto, reducimos el bucle de retroalimentación de días a horas y evitamos el costoso retrabajo que ocurre cuando las suposiciones sobre la forma de la carga o el manejo de errores resultan ser incorrectas.

Cuando existe un contrato desde el principio, los diseñadores pueden crear componentes de UI que consumen la forma de datos exacta, QA puede escribir casos de prueba basados en las respuestas de error definidas, y DevOps puede configurar servidores de mock en entornos de staging sin esperar al servicio real. El contrato se convierte en una sola fuente de verdad que reduce la mala comunicación entre disciplinas.

Escribir el contrato

Un contrato necesita capturar cada comportamiento observable del endpoint. Comienzo con la ruta HTTP y el método, luego anoto cualquier esquema de autenticación (clave de API, token de portador, TLS mutuo). A continuación, listo los parámetros de la solicitud: cadenas de consulta, encabezados y campos del cuerpo, marcando cada uno como requerido u opcional. Para cada campo, agrego un tipo (cadena, número, booleano, matriz, objeto) y un formato si es necesario (correo electrónico, fecha-hora, uuid). Luego defino la respuesta de éxito: código de estado, cualquier encabezado y la forma completa de la carga útil con tipos y formatos. Finalmente, agrego casos de error que el frontend debe manejar: errores de validación (400), no encontrado (404), no autorizado (401), limitado por tarifa (429) y errores del servidor (5xx). Para cada error, incluyo un cuerpo de muestra que muestra la forma del mensaje de error.

Elemento del contrato | Valor de ejemplo | Notas Ruta | /v1/pedidos | Recurso con versión Método | POST | Crea un nuevo pedido Autenticación | Token de portador | Encabezado de autorización requerido Cuerpo de la solicitud – requerido | customer_id (cadena, uuid) | Debe existir en la base de datos Cuerpo de la solicitud – opcional | nota (cadena, máximo 500) | Comentario de forma libre Respuesta de éxito | 201, {order_id, created_at} | Encabezado de ubicación con URL Error de validación | 400, {errors: [{field: "customer_id", message: "must be uuid"}]} | Ayuda al frontend a mostrar advertencias en línea No encontrado | 404, {error: "pedido no encontrado"} | Ocurre en GET /v1/pedidos/:id cuando el id es desconocido

Mantengo el contrato en un archivo de texto plano (YAML o JSON) que vive junto a la rama de función. Esto hace que sea fácil difundir los cambios durante la revisión de código y almacenar el artefacto en control de versión junto con el código fuente. Cuando un contrato cambia, la difusión muestra exactamente qué campo se agregó, eliminó o alteró su tipo, lo que provoca una conversación entre los propietarios del frontend y el backend antes de que se escriba cualquier código.

Generación de la especificación de simulación

Una vez que el contrato esté escrito en un archivo simple de markdown o JSON, MockDeck lo lee y produce tres artefactos: un documento OpenAPI 3, una colección Postman y un archivo de rutas sin procesar (JSON plano con ruta, método y respuestas de ejemplo). La salida de OpenAPI incluye los esquemas exactos que definiste, además de ejemplos generados automáticamente que se parecen a datos reales — piensa en nombres que siguen patrones típicos, números que caen dentro de rangos esperados y cadenas que alcanzan longitudes mínimas y máximas. La colección Postman se puede importar directamente al cliente de API que usas para pruebas manuales, y el archivo de rutas sin procesar se puede servir con un servidor de simulación ligero (como Mirage JS o json-server) con cero configuración.

El paso de generación es determinista: dado el mismo archivo de contrato, siempre obtienes la misma salida de simulación. Esto te permite comprometer los artefactos generados con tu repositorio si deseas una simulación estática, o puedes ejecutar MockDeck como parte del inicio de tu servidor de desarrollo para mantener la simulación en memoria. Debido a que la simulación se deriva del contrato, nunca tienes que mantener dos fuentes de verdad separadas; cualquier cambio en el contrato se propaga automáticamente a la simulación cuando la regeneras.

MockDeck también agrega algunas características de conveniencia de forma predeterminada: establece los encabezados CORS adecuados para el desarrollo local, agrega un control deslizante de latencia para que puedas simular el retraso de la red y registra cada solicitud en la consola para que puedas verificar que el frontend está golpeando el punto final esperado con la carga útil correcta.

Integración de mocks en el flujo de trabajo de frontend

En mis proyectos, agrego un script de inicio que lanza el servidor de mocks antes del servidor de desarrollo de frontend. El script lee la carpeta de contrato, ejecuta MockDeck para producir el archivo de rutas y luego inicia un servidor node-express que sirve esas rutas en http://localhost:3001. El proxy de frontend está configurado para reenviar todas las solicitudes de /api a ese puerto, por lo que la base de código ve una capa de API suave sin cambios en el código fuente.

- Agrega un directorio de contratos en la raíz del repositorio. - Para cada punto final, crea un archivo.yaml que sigue la estructura descrita anteriormente. - Agrega un script de inicio:mock en package.json que ejecuta mockdeck build./contracts --out./mock y luego node./mock/server.js. - Configura el servidor de desarrollo de frontend (por ejemplo, Vite, CRA) para que proxy /api a http://localhost:3001. - Ejecuta npm run start:mock en un terminal y npm run dev en otro.

Cuando un contrato cambia, solo necesitas reiniciar el script de mock; el frontend recoge el nuevo comportamiento al instante porque el proxy reenvía al servidor de mock actualizado. Este ciclo ajustado anima a los desarrolladores a tratar el contrato como el primer artefacto que modifican cuando evoluciona una característica.

También escribo una prueba simple de Jest que importa el documento de OpenAPI generado y afirma que la forma de la solicitud coincide con las llamadas de API del componente. Esto proporciona una red de seguridad adicional: si un desarrollador cambia accidentalmente la carga útil de la solicitud en la UI, la prueba falla y señala al contrato como la fuente de verdad.

Control de versiones de contratos y manejo de divergencias

Los contratos evolucionan al igual que el código. Trato cada archivo de contrato como una versión junto con la rama de características. Cuando se necesita un cambio importante, como cambiar el nombre de un campo o modificar una bandera requerida, creo una nueva versión del contrato (por ejemplo, v2/order-create.yaml) y actualizo el generador de OpenAPI para que incluya un bloque de servidores que apunte a la ruta de versión. El servidor de simulación sirve ambas versiones simultáneamente, lo que permite al frontend optar por el nuevo contrato cambiando la URL base.

Para detectar divergencias, ejecuto un trabajo nocturno que compara la especificación de OpenAPI del backend en vivo (generada a partir del código real) con la especificación generada por el contrato. Cualquier discrepancia se informa como una advertencia en nuestro panel de CI. Este enfoque ha detectado casos en los que un desarrollador de backend agregó un nuevo campo opcional sin actualizar el contrato, lo que habría causado errores de validación en el frontend en producción.

Cuando un contrato está en desuso, agrego una fecha de ocaso en un comentario en la parte superior del archivo y mantengo la simulación activa durante dos semanas después de la fecha para dar tiempo a los equipos a migrar. Después de ese período, el servidor de simulación devuelve una respuesta de 410 Gone con una breve explicación, lo que hace que el ciclo de vida del contrato sea explícito.

Pruebas de contrato como red de seguridad

Las pruebas de contrato verifican que el MockDeck y la implementación real hablen el mismo lenguaje. Utilizo una herramienta como Pact o Dredd para ejecutar el contrato contra ambos, el servidor mock y el backend de staging. La suite de pruebas envía cada solicitud definida en el contrato, verifica el código de estado de respuesta, los encabezados y el esquema del cuerpo, y registra cualquier desviación.

Incorporar este paso en el flujo de solicitud de extracción significa que un cambio en el backend que rompa el contrato fallará la compilación antes de llegar al master. De manera similar, si un desarrollador frontend actualiza la carga de la solicitud sin actualizar el contrato, la prueba fallará porque el mock no reconocerá la nueva forma.

Para equipos centrados en la seguridad, también ejecuto el contrato contra las directrices de OWASP (https://owasp.org/www-project-top-10-for-large-language-model-applications) para asegurarme de que los mocks generados no expongan inadvertidamente patrones peligrosos, como la carga de archivos sin restricciones o la fuga excesiva de datos. Además, me refiero al marco de gestión de riesgos de AI de NIST (https://www.nist.gov/itl/ai-risk-management-framework) al revisar cómo el mock maneja los puntos finales de toma de decisiones automatizados, asegurándome de que los mensajes de error no revelen internos del modelo.

La suite de pruebas de contrato se ejecuta en menos de dos segundos en una laptop típica, por lo que agrega una sobrecarga negligible al pipeline de CI mientras entrega una alta confianza de que el mock permanece fiel a la especificación acordada.

Qué no es esto

Este enfoque no garantiza que el backend se entregue según el calendario. Un mock solo puede simular comportamiento, no puede reemplazar la lógica de negocio real, las interacciones con la base de datos o las llamadas a servicios externos que realizará la implementación real.

No es un sustituto del 100 % para las pruebas de extremo a extremo. Todavía necesitas verificar que el sistema integrado funcione correctamente con datos auténticos, características de rendimiento y condiciones de error que pueden aparecer solo bajo carga.

No elimina la necesidad de una comunicación clara entre equipos. El contrato es una herramienta para facilitar la discusión, pero no reemplaza las reuniones regulares, las revisiones de diseño o la documentación compartida.

Finalmente, el uso de mocks de contrato en primer lugar no hará que tu producto sea inmune a errores de especificación. Si el contrato en sí es ambiguo o incompleto, el mock implementará fielmente esas lagunas y el frontend se construirá sobre una suposición defectuosa. Trata el contrato como un documento vivo que evoluciona con la retroalimentación de ambos lados.

Referencias

- https://owasp.org/www-project-top-10-for-large-language-model-applications

- https://www.nist.gov/itl/ai-risk-management-framework

Preguntas frecuentes

¿Es este un servidor de simulación en ejecución?

No. MockDeck genera la especificación de la API de simulación - OpenAPI 3, Postman o rutas raw. Servirlo es un paso separado.

¿Puede llamar a nuestro backend real?

No. No proxy o ejecuta su backend; la salida es una especificación y respuestas de muestra.

¿Qué formatos produce?

OpenAPI 3, colecciones de Postman o rutas raw.

¿Por qué molestarse con respuestas de error en una simulación?

Porque ese es donde el código frontend generalmente se rompe. Una simulación que solo devuelve 200s oculta los estados que más necesita manejar.

¿Qué tan realista es el dato de muestra?

Se genera para parecerse a las cargas útiles reales, lo que es suficiente para detectar errores de formato y estado vacío temprano. No es datos de producción.

¿Valida nuestra API existente contra el contrato?

No. Las pruebas de contrato y la validación son herramientas separadas.

No, MockDeck es una herramienta independiente.

Referencias

- Especificación OpenAPI - Esquema JSON

Prueba el producto: MockDeck

20-09-2026 · solo fuentes primarias · no métricas de tráfico fabricadas · solo para toma de decisiones

Artículos relacionados

- Servidores Mock vs ejemplos de OpenAPI - Explora la matriz completa de temas de micro-SaaS de IA →