Derivar un cliente de API a partir de una sesión grabada
Conducir un navegador es la herramienta adecuada para la primera visita y la herramienta equivocada para la centésima. Esta habilidad graba el tráfico de red de un sitio una vez mientras lo usas, y luego convierte las solicitudes capturadas en un cliente independiente (script, CLI o biblioteca) que se comunica directamente con la API interna del sitio.
La grabación por sí sola contiene todo lo necesario: agent-browser incrusta los cuerpos de respuesta de texto (JSON/HTML/JS) en el HAR de forma predeterminada, por lo que las formas de los endpoints se pueden estudiar sin conexión después de cerrar el navegador.
Flujo de trabajo
1. Grabar Iniciar la captura HAR, realizar los flujos deseados en el cliente
2. Identificar Encontrar los endpoints reales de la API entre el ruido
3. Extraer Obtener las formas de las solicitudes, esquemas de respuesta y material de autenticación
4. Generar Escribir el cliente, una función por flujo
5. Verificar Llamar a cada endpoint realmente antes de declarar que está terminado
1. Grabar
agent-browser network har start # incrusta cuerpos de respuesta de texto de forma predeterminada
# ... navegar por el sitio: buscar, abrir una página de detalle, paginar, etc. ...
agent-browser network har stop /tmp/site.har
- Ejecuta cada flujo que el cliente deba soportar y ejecuta cada uno al menos dos veces con entradas diferentes (dos términos de búsqueda, dos páginas de detalle). Diferenciar las URLs grabadas revela qué partes son parámetros.
- Si el sitio requiere inicio de sesión, inicia sesión antes de comenzar el HAR para que las credenciales no terminen en la grabación innecesariamente. Las cookies de sesión se exportan por separado en el paso 3.
--content alltambién incrusta cuerpos binarios (base64);--content nonedeshabilita la incrustación. El límite por cuerpo es de 2 MB.
Mientras la sesión aún está abierta, agent-browser network requests y network request <id> proporcionan los mismos datos de forma interactiva, pero solo el HAR sobrevive a la navegación y al cierre del navegador, por lo que es preferible para cualquier cosa que abarque varias páginas.
2. Identificar endpoints
Consulta el HAR con jq:
# Todas las llamadas JSON de la API: método, URL, estado
jq -r '.log.entries[]
| select(.response.content.mimeType | test("json"))
| "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har
Ignora el ruido de analíticas e infraestructura: endpoints de telemetría (/collect, /track, /beacon, /log), dominios de terceros (google-analytics, segment, sentry, datadog, intercom, hotjar) y activos estáticos. La API real suele ser propia, JSON y se correlaciona con las acciones que realizaste.
3. Extraer formas y autenticación
# Detalle completo de un endpoint: encabezados de solicitud, cuerpo POST, cuerpo de respuesta
jq '.log.entries[] | select(.request.url | test("api/search"))
| {request: {method: .request.method, headers: .request.headers,
postData: .request.postData.text},
response: .response.content.text}' /tmp/site.har
- Esquema de respuesta: lee
.response.content.text— es la carga útil real, úsala para derivar tipos. - Autenticación: compara los encabezados de solicitud entre endpoints. Busca
authorization,cookie,x-csrf-token,x-api-keyy encabezadosx-*específicos del sitio. Replica solo los que importan: pruébalos omitiéndolos en el paso 5. - Cookies: exporta la sesión activa con
agent-browser cookies get --json > cookies.jsonpara que el cliente las cargue en tiempo de ejecución. Nunca codifiques valores de cookies en el código fuente generado.
4. Generar el cliente
- Una función por flujo grabado (
search(query),getItem(id)), tipada a partir de los cuerpos de respuesta observados. - El material de autenticación (cookies, tokens Bearer) se carga desde un archivo o variable de entorno, con un error claro que le indique al usuario que vuelva a iniciar sesión en el navegador cuando caduque.
- Reproduce los encabezados que la API realmente requiere: algunos sitios devuelven 403 sin un
user-agent,refererox-requested-withcoincidentes. - Mantén los parámetros de paginación, ordenación y filtro que aparecieron en las cadenas de consulta grabadas como opciones de función.
5. Verificar
Llama a cada función generada contra la API real y compara la forma de la respuesta con la grabación. Fallos comunes:
| Síntoma | Causa | Solución |
|---|---|---|
| 401/403 | Sesión caducada o faltante | Vuelve a iniciar sesión mediante agent-browser, reexporta las cookies |
| 403/419 en escrituras | El token CSRF es por sesión o por formulario | Obtén primero el endpoint del token o mantén ese flujo basado en el navegador |
| Funciona y luego falla | Parámetros de solicitud firmados/con caducidad | Recae en el navegador para ese paso; deriva el resto |
| Forma diferente al HAR | Pruebas A/B o respuestas dependientes de la ubicación | Regraba y trata la unión como campos opcionales |
Advertencias
- Las API internas no tienen versión y cambian sin previo aviso: conserva el HAR para poder rederivar el cliente.
- Respeta los términos de servicio y límites de velocidad del sitio; añade demoras para la obtención masiva.
- Los archivos HAR contienen credenciales de sesión activa (cookies, tokens, cuerpos POST). Trátalos como secretos: mantenlos fuera del control de versiones y elimínalos cuando hayas terminado.