Generador de Respuestas API Simuladas

Acerca de Generador de Respuestas API Simuladas

El front-end casi nunca espera al back-end. Si la API todavía no existe, o existe pero no es fácil conseguir que devuelva una lista vacía, la última página o un 422, se trabaja contra respuestas falsas. Este generador toma una lista de campos y una forma de «sobre» (envelope) y produce una respuesta con esa forma. Hay seis: array simple, envoltorio data, respuesta paginada con meta y links, recurso único, JSON:API y cuerpo de error.

Si indicas una semilla, un pequeño generador pseudoaleatorio (mulberry32) extrae los valores siempre en el mismo orden, así que la misma semilla da la misma respuesta. Las fechas no se calculan a partir de hoy sino de un ancla fija, el 1 de enero de 2024 (UTC), dentro de los cinco años anteriores (de 2019 a 2023). Eso mantiene estables los tests de snapshot. Las fechas solo van hacia atrás, así que una «fecha de alta» nunca queda en el futuro, pero una vista que filtre «los últimos 7 días» respecto a hoy no encontrará nada.

Lo que un mock demuestra y lo que no

Un mock responde bien a una pregunta: ¿mi interfaz se comporta correctamente cuando recibe datos con esta forma? ¿Se detiene el spinner, se desactiva el botón «Siguiente» cuando links.next es null, un nombre de 40 caracteres salta de línea en lugar de romper la tarjeta?

Lo que no puede decirte es si el servidor real envía de verdad esa forma. Un mock es la API que imaginaste. Si el equipo de back-end cambia user_name por username, todos los tests montados sobre tu mock siguen pasando mientras producción falla. Para cerrar esa brecha existen las pruebas de contrato. La documentación de Pact las describe como comprobar cada aplicación por separado para asegurar que los mensajes que envía o recibe se ajustan a un entendimiento común documentado en un «contrato». En el flujo de Pact, guiado por el consumidor, el archivo de contrato se genera mientras corren los tests del consumidor, y después el proveedor reproduce esas interacciones contra su propio código.

En la práctica se usan ambas cosas. Mocks como estos sirven para construir pantallas rápido y reproducir estados límite cuando quieras. Las pruebas de contrato, o la validación contra un esquema OpenAPI, son las que detectan desajustes entre cliente y servidor antes de publicar. Conviene dejar claro en el equipo que la salida de esta herramienta es un ejemplo ilustrativo, no el contrato.

Cómo se calculan los números de paginación

total_pages es total dividido entre per_page, redondeado hacia arriba y nunca menor que 1. La cantidad de elementos de la página actual es total − (page − 1) × per_page, limitada entre 0 y per_page. El campo id es una secuencia de toda la colección: con diez por página, la página 3 empieza en el id 21, igual que en una API real basada en offset.

Con total en 0 obtienes un array vacío y total_pages igual a 1, útil para diseñar el estado «sin resultados». Si pides una página posterior a la última, obtienes un array vacío con next en null. Las APIs reales no coinciden en este caso: unas devuelven una página vacía y otras un 404. Comprueba cuál es el comportamiento de tu servidor antes de construir el manejo de errores.

Los enlaces siguen el estilo page/per_page (…/users?page=2&per_page=10). Si tu API pagina con cursores, los bloques meta y links no coincidirán y solo el array data será reutilizable.

Los errores tienen un estándar

El sobre de error que genera la herramienta es { error: { status, code, message, request_id } }, con un array details cuando el estado es 422. Es una forma habitual, pero es una convención, no un estándar. El estándar para errores de APIs HTTP es la RFC 9457, Problem Details: usa el tipo de medio application/problem+json y los miembros type, title, status, detail e instance, y si falta type se asume about:blank. Si el servicio con el que integras sigue la RFC 9457, cambia los nombres de las claves para probar tu manejo de errores con la forma correcta.

Un detalle de nombres: la RFC 9110 renombró el estado 422 como «Unprocessable Content» (antes era Unprocessable Entity), y la herramienta imprime el nombre nuevo. Los clientes no deben interpretar esa frase, así que un servidor que siga enviando la antigua no rompe nada, pero conviene saberlo si comparas con la especificación. El valor code del cuerpo de error (unprocessable_entity) es una cadena de convención propia de cada API, así que se deja tal cual.

Qué cambia en el modo JSON:API

En modo JSON:API cada registro pasa a ser { type, id, attributes }. El campo id sale de attributes y se emite como cadena, porque la especificación exige identificadores de recurso de tipo string. En el nivel superior aparecen jsonapi.version con valor 1.1, meta y links. No se generan relationships ni included, así que si tu pantalla muestra datos relacionados tendrás que añadir esos bloques a mano.

Ejemplos

Cómo se usa

1. Añade los campos del recurso y elige un tipo para cada uno. integer y float aceptan «mín,máx»; pick acepta opciones separadas por comas.
2. Elige el estilo de sobre y fija total, page y per_page. En el estilo de error, elige el código de estado y, si quieres, el mensaje.
3. Introduce una semilla si necesitas repetir la salida y activa la cabecera HTTP si tu fixture la necesita.
4. Copia el resultado en tu servidor de mocks (MSW, json-server, etc.) o en un archivo de fixtures.

Preguntas frecuentes