Funciones centrales de ApiCatcher: introducción y escenarios de uso

ApiCatcher captura y depura HTTP/HTTPS en iOS, Android, macOS y Windows. En el teléfono el tráfico pasa por una VPN local, así que el dispositivo no tiene que usar un ordenador como proxy. En el escritorio se cambia entre el proxy del sistema y TUN. TUN es para las apps que ignoran el proxy del sistema.

La «Api» del nombre viene del problema inicial: una petición capturada no debería quedarse como una fila del historial. Tiene que convertirse en una API con la que se pueda seguir trabajando. De cada una de las ocho funciones se dice qué problema resuelve y qué escenarios de uso le corresponden.

Captura

Es la puerta de todo lo demás. Al activarla, el HTTP/HTTPS de las apps y del navegador pasa por el proxy local. Si se instala y se confía el certificado de la CA, el HTTPS se lee en claro. También quedan el handshake y las tramas de WebSocket. Las tramas se ven como un chat, el JSON va resaltado y se puede buscar en el payload.

Lo que se usa al lado:

• Listas de permiso y de bloqueo, por host. Si la de permiso no está vacía, solo se guardan los hosts que coinciden. Los de la de bloqueo no se registran. Vale *, por ejemplo *.example-api.com.
• Sesiones: de inicio a parada es una sesión. El historial se puede limitar a esa captura, o borrar la sesión entera.
• Búsqueda en la URL, cabeceras de petición y de respuesta, cuerpo de petición y cuerpo de respuesta. También se filtra por método, protocolo, Content-Type, código de estado y rango de tiempo.
• Exportación de una petición como Raw, cURL o Markdown, o de un lote como HAR. Imágenes, vídeo y audio van aparte. Los fragmentos Range se unen antes de exportar.

Escenario de uso: problemas de la API. Se repite la acción que falló, se abre esa petición en el historial y se compara la URL, las cabeceras y el cuerpo que el cliente envió de verdad con el código y el cuerpo que devolvió el servidor. Si la petición ya está mal, el problema está en el cliente. Si la petición es correcta y la respuesta no, está en el servidor. Eso se aclara antes de seguir.

Escenario de uso: qué APIs usa una función. Se recorre esa función una vez por cada escenario de negocio. El historial muestra qué APIs tocó y en qué cambian los parámetros entre escenarios.

API generada automáticamente

Las peticiones HTTP/HTTPS que encajan se convierten en documentación de API, agrupada por host. Una operación se identifica por método + host + ruta. Las capturas posteriores de la misma operación solo añaden campos que aún no habían aparecido. No cambian el nombre de un campo que ya está. El ejemplo de respuesta se actualiza solo cuando el estado es 200.

Se exporta un host entero, una sola API o una carpeta de favoritos, a Postman, Apifox o un ZIP de Bruno.

Escenario de uso: exportar a un gestor de API. Con los documentos ya generados, se exporta el host, una API o una carpeta de favoritos a Postman, Apifox o Bruno, y allí se mantiene y se comparte.

A diferencia de exportar un HAR e importarlo en Postman u otra plataforma de gestión de API, las API que genera ApiCatcher se completan conforme cubres más escenarios de negocio con tus capturas: cuantos más escenarios, más campos quedan documentados.

Reproducción

La reproducción es ApiCatcher actuando otra vez como cliente. Toma una petición HTTP/HTTPS del historial, cambia o no la query, las cabeceras y el cuerpo, la envía al servidor y muestra el estado y la respuesta en la página de reproducción. La app no refresca la pantalla por eso. En WebSocket se reconecta aquí, se envía una trama a mano y se lee lo que vuelve.

Si la captura está en marcha, la reproducción pasa por el proxy local. Así se aplican las reglas de reescritura y los scripts, y la llamada vuelve a salir en el historial.

Escenario de uso: integración de API. Cuando el backend ya cambió la API, o le añadió logs para seguir el problema, se reproduce de un toque la petición recién capturada. Con un solo envío se ve si el fallo desapareció, y esa llamada entra en los logs nuevos.

Reproducción combinada

La reproducción combinada pone varias peticiones HTTP/HTTPS en un lienzo y las ejecuta según dependencias. Los nodos que no dependen entre sí van en paralelo. Los que dependen van en serie: el siguiente nivel no arranca hasta que el anterior haya terminado bien por completo.

Cuatro ediciones que se usan siempre:

Escenario de uso: integración de una cadena de llamadas. La petición posterior necesita la respuesta anterior. Se pone la dependencia, se inyecta la respuesta anterior en la petición siguiente y se ejecutan en ese orden. Por ejemplo, GET /user depende de POST /login, y POST /order depende de GET /user. En las dos últimas se inyecta el token en Authorization, y el orden es inicio de sesión, datos del usuario y pedido.

Escenario de uso: misma API, distintas entradas. Se añade esa petición varias veces. Si tienen que ir una detrás de otra, se encadenan todos los nodos solo con dependencia, sin inyección. Cada nodo lleva su cuerpo en los parámetros previstos. Al terminar se comparan los resultados. Por ejemplo, el inicio de sesión tres veces: cuenta válida, contraseña incorrecta y contraseña vacía.

Reescritura

La reescritura cambia el tráfico antes de que la petición llegue al servidor, o antes de que la respuesta vuelva a la app. Una regla es un alcance más una acción. El alcance es un host, con ruta y método opcionales.

Acciones:

• Redirección: mandar un dominio de producción a la máquina local o a preproducción.
• Mock: no enviar la petición real y devolver un estado, unas cabeceras y un cuerpo previstos.
• Descartar petición / descartar respuesta: simular un envío que no sale, o un servidor que no contesta.
• Retraso: retener la respuesta para ver la carga y el tiempo de espera en una red lenta.
• Modificación: cambiar cabeceras, sustituir el cuerpo entero o buscar y reemplazar dentro del cuerpo con una expresión regular. La expresión la puede redactar la IA a partir de una frase.

Escenario de uso: mock de API. El backend aún no está, o el cliente tiene que llegar a un estado concreto. Se devuelve un estado y un cuerpo previstos, sin llamada real. Por ejemplo, una lista de pedidos con «pendiente de pago» y «completado»: las pantallas se terminan y la regla se apaga cuando la API existe.

Escenario de uso: reescritura de la respuesta. Se tocan unos campos y se mira qué hace después el cliente, sin modificar datos del servidor. Por ejemplo, sustituir "balance": 100 por "balance": 0 y ver el botón cuando no queda saldo.

Scripts

Si el valor cambia en cada llamada, una regla fija no alcanza. Se usa JavaScript. Una petición que coincide entra en interceptRequest y la respuesta en interceptResponse. Se escribe a mano, la redacta la IA o se indica una URL de script en la red local que reparte el equipo.

Disponible en el script:

• crypto para MD5, SHA, HMAC y Base64, para firmar o para cifrar y descifrar un cuerpo.
• localStore para guardar un token u otro estado entre peticiones.
• httpClient para hacer otra llamada HTTP desde el script, por ejemplo volver a iniciar sesión si el token caducó.

Escenario de uso: cálculo dinámico de la petición. Una firma o una marca de tiempo cambia en cada llamada: un reemplazo fijo no sirve. Se calcula con esta petición y luego se deja pasar. Si la reproducción devuelve siempre 401, se hace un HMAC de la hora y el cuerpo y se rellenan X-Timestamp y X-Signature. La captura tiene que estar en marcha antes de reproducir; si no, el script no actúa sobre esa llamada.

Escenario de uso: cifrado y descifrado del cuerpo. En los proyectos internos el cuerpo suele ir cifrado además del HTTPS. Al abrir TLS se sigue viendo texto cifrado. El script cifra antes de enviar y descifra al volver la respuesta, para leer y cambiar el texto en claro. Por ejemplo, descifrar el cuerpo de la respuesta en interceptResponse. Al reproducir, volver a cifrar el texto modificado en interceptRequest. Sin la captura en marcha, el script no se ejecuta.

Suplantación de DNS

En el producto se llama asignación DNS. La suplantación ocurre en el proxy. No se toca el archivo hosts ni el DNS del Wi-Fi. Con la captura activa, una conexión que coincide se salta la resolución pública y abre TCP contra la IP indicada. La cabecera Host y el SNI de TLS siguen siendo el nombre original: la app no se entera. Los comodines valen, por ejemplo *.apicatcher.net.

Escenario de uso: mismo dominio para prueba o preproducción. Prueba, preproducción y producción usan el mismo dominio. Para llegar a prueba o a preproducción se apunta ese dominio al entorno que toca. En la asignación DNS se pone la IP de prueba o de preproducción. Tiene efecto al iniciar la captura: no hace falta cambiar el DNS del Wi-Fi cada vez, y no hay pelea con la caché DNS del sistema.

Tareas programadas

Una tarea ejecuta una reproducción, o una reproducción combinada entera, según un plan.

• Cron: seis campos, en orden segundo, minuto, hora, día, mes, día de la semana. 0 * * * * ? es el segundo 0 de cada minuto. Si la sintaxis no está clara, la IA la escribe a partir de una frase.
• Personalizado: se repite cada N segundos, con un tope de veces o de minutos.

La tarea se detiene cuando se cumple una condición de parada automática. En el historial de ejecución se ven la duración y la tasa de éxito. En el teléfono la tarea solo corre con la captura activa. En el escritorio basta con que la aplicación esté abierta.

Escenario de uso: envío programado. La ventana es corta y un clic a mano se pierde con facilidad. Se envía una petición, o una reproducción combinada, a intervalo, y se para según la respuesta. Por ejemplo, unos segundos antes de una venta relámpago, un pedido cada segundo. Se para cuando code es 200, o cuando el cuerpo dice que la compra salió o que la venta terminó.

Escenario de uso: comprobación programada. Se llama a la misma API con un ritmo fijo y se mira si sigue respondiendo y si se ha vuelto lenta. Un control de salud con cron 0 * * * * ? sale una vez por minuto. Sin parada automática, y el P95 se lee en el historial.

Escenario de uso: regresión programada. Se programa una reproducción combinada ya armada y se mira si los resultados siguen siendo los esperados. Se añade la misma API varias veces y en cada nodo se prevé una entrada distinta. Esos nodos son los casos de prueba. Esa combinación se ejecuta una vez por semana. Si las llamadas necesitan antes un inicio de sesión, se añade una sola petición de login como predecesora común de todas las demás. Esas otras peticiones solo pueden ir en paralelo entre sí.

El detalle de los pasos está en la documentación: manual, reescritura, scripts, reproducción combinada, tareas programadas.

Lo anterior no agota las funciones de ApiCatcher. Más información en la web oficial. Los escenarios de uso que listamos no significan que solo sirvan para eso: son los problemas que queríamos resolver cuando diseñamos cada función.