Derivar um cliente de API a partir de uma sessão gravada
Dirigir um navegador é a ferramenta certa para a primeira visita e a ferramenta errada para a centésima. Esta skill grava o tráfego de rede de um site uma vez enquanto você o utiliza e, em seguida, transforma as requisições capturadas em um cliente autônomo (script, CLI ou biblioteca) que se comunica diretamente com a API interna do site.
A gravação sozinha contém tudo o que é necessário: o agent-browser incorpora corpos de resposta de texto (JSON/HTML/JS) no HAR por padrão, permitindo que os formatos dos endpoints sejam estudados offline após o navegador ser fechado.
Fluxo de Trabalho
1. Gravar Iniciar a captura HAR, executar os fluxos desejados no cliente
2. Identificar Encontrar os endpoints reais da API em meio ao ruído
3. Extrair Extrair formatos de requisição, esquemas de resposta e material de autenticação
4. Gerar Escrever o cliente, uma função por fluxo
5. Verificar Chamar cada endpoint para validação antes de declarar concluído
1. Gravar
agent-browser network har start # incorpora corpos de resposta de texto por padrão
# ... use o site: pesquise, abra uma página de detalhes, pagine, etc. ...
agent-browser network har stop /tmp/site.har
- Execute todos os fluxos que o cliente deve suportar e execute cada um pelo menos duas vezes com entradas diferentes (dois termos de pesquisa, duas páginas de detalhes). Diferenciar as URLs gravadas revela quais partes são parâmetros.
- Se o site exigir login, faça login antes de iniciar o HAR para que as credenciais não sejam gravadas desnecessariamente. Os cookies de sessão são exportados separadamente na etapa 3.
--content alltambém incorpora corpos binários (base64);--content nonedesabilita a incorporação. O limite por corpo é de 2 MB.
Enquanto a sessão ainda estiver ativa, agent-browser network requests e network request <id> fornecem os mesmos dados de forma interativa — mas apenas o HAR sobrevive à navegação e ao fechamento do navegador, portanto, prefira-o para qualquer coisa que envolva várias páginas.
2. Identificar endpoints
Consulte o HAR com jq:
# Todas as chamadas JSON da API: método, URL, status
jq -r '.log.entries[]
| select(.response.content.mimeType | test("json"))
| "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har
Ignore telemetria e ruído de infraestrutura: endpoints de telemetria (/collect, /track, /beacon, /log), domínios de terceiros (google-analytics, segment, sentry, datadog, intercom, hotjar) e ativos estáticos. A API real geralmente é própria, JSON e correlacionada com as ações que você executou.
3. Extrair formatos e autenticação
# Detalhes completos para um endpoint: cabeçalhos da requisição, corpo POST, corpo da resposta
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 da resposta: leia
.response.content.text— este é o payload real; use-o para derivar tipos. - Autenticação: compare os cabeçalhos das requisições entre os endpoints. Procure por
authorization,cookie,x-csrf-token,x-api-keye cabeçalhosx-*específicos do site. Replique apenas os que são importantes — teste por omissão na etapa 5. - Cookies: exporte a sessão ativa com
agent-browser cookies get --json > cookies.jsonpara o cliente carregar em tempo de execução. Nunca codifique valores de cookie no código-fonte gerado.
4. Gerar o cliente
- Uma função por fluxo gravado (
search(query),getItem(id)), tipada a partir dos corpos de resposta observados. - O material de autenticação (cookies, tokens bearer) é carregado de um arquivo ou variável de ambiente, com um erro claro informando ao usuário para refazer o login no navegador quando expirar.
- Reproduza os cabeçalhos que a API realmente exige — alguns sites retornam 403 sem um
user-agent,refereroux-requested-withcorrespondente. - Mantenha os parâmetros de paginação, ordenação e filtro que apareceram nas strings de consulta gravadas como opções de função.
5. Verificar
Chame cada função gerada contra a API ativa e compare o formato da resposta com a gravação. Falhas comuns:
| Sintoma | Causa | Correção |
|---|---|---|
| 401/403 | Sessão expirada ou ausente | Refazer login via agent-browser, reexportar cookies |
| 403/419 em escritas | Token CSRF é por sessão ou por formulário | Buscar o endpoint do token primeiro, ou manter esse fluxo baseado no navegador |
| Funciona e depois quebra | Parâmetros de requisição assinados/com expiração | Recorrer ao navegador para essa etapa; derivar o restante |
| Formato diferente do HAR | Testes A/B ou respostas dependentes de localização | Regravar e tratar a união como campos opcionais |
Advertências
- APIs internas não têm versão e mudam sem aviso — mantenha o HAR para que o cliente possa ser rederivado.
- Respeite os termos de serviço e limites de taxa do site; adicione atrasos para buscas em massa.
- Arquivos HAR contêm credenciais de sessão ativas (cookies, tokens, corpos POST). Trate-os como segredos: mantenha-os fora do controle de versão e exclua-os quando terminar.