Dériver un client API à partir d'une session enregistrée
Lancer un navigateur est le bon outil pour la première visite, mais le mauvais outil pour la centième. Cette compétence enregistre le trafic réseau d'un site une fois pendant que vous l'utilisez, puis transforme les requêtes capturées en un client autonome (script, CLI ou bibliothèque) qui communique directement avec l'API interne du site.
L'enregistrement seul contient tout le nécessaire : agent-browser intègre les corps de réponse texte (JSON/HTML/JS) dans le HAR par défaut, ce qui permet d'étudier la forme des endpoints hors ligne après la fermeture du navigateur.
Flux de travail
1. Enregistrer Démarrer la capture HAR, parcourir les flux souhaités dans le client
2. Identifier Trouver les vrais endpoints API parmi le bruit
3. Extraire Extraire les paramètres de requête, schémas de réponse, et éléments d'authentification
4. Générer Écrire le client, une fonction par flux
5. Vérifier Appeler chaque endpoint en réel avant de déclarer terminé
1. Enregistrer
agent-browser network har start # intègre les corps de réponse texte par défaut
# ... parcourir le site : rechercher, ouvrir une page détail, paginer, etc. ...
agent-browser network har stop /tmp/site.har
- Exécutez chaque flux que le client doit supporter, et exécutez chacun au moins deux fois avec des entrées différentes (deux termes de recherche, deux pages détail). La comparaison des URL enregistrées révèle quelles parties sont des paramètres.
- Si le site nécessite une connexion, connectez-vous avant de démarrer le HAR afin que les identifiants ne soient pas inclus inutilement dans l'enregistrement. Les cookies de session sont exportés séparément à l'étape 3.
--content allintègre également les corps binaires (base64) ;--content nonedésactive l'incorporation. La limite par corps est de 2 Mo.
Tant que la session est ouverte, agent-browser network requests et network request <id> fournissent les mêmes données de manière interactive — mais seul le HAR survit à la navigation et à la fermeture du navigateur, donc préférez-le pour tout ce qui est multi-page.
2. Identifier les endpoints
Interrogez le HAR avec jq :
# Tous les appels API JSON : méthode, URL, statut
jq -r '.log.entries[]
| select(.response.content.mimeType | test("json"))
| "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har
Ignorez le bruit d'analyse et d'infrastructure : endpoints de télémétrie (/collect, /track, /beacon, /log), domaines tiers (google-analytics, segment, sentry, datadog, intercom, hotjar), et ressources statiques. La vraie API est généralement first-party, JSON, et corrélée avec les actions que vous avez effectuées.
3. Extraire les paramètres et l'authentification
# Détail complet pour un endpoint : en-têtes de requête, corps POST, corps de réponse
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
- Schéma de réponse : lisez
.response.content.text— c'est la charge utile réelle, utilisez-la pour dériver les types. - Authentification : comparez les en-têtes de requête entre les endpoints. Cherchez
authorization,cookie,x-csrf-token,x-api-key, et les en-têtesx-*spécifiques au site. Ne rejouez que ceux qui comptent — testez par omission à l'étape 5. - Cookies : exportez la session active avec
agent-browser cookies get --json > cookies.jsonpour que le client les charge au moment de l'exécution. N'écrivez jamais en dur des valeurs de cookies dans le code source généré.
4. Générer le client
- Une fonction par flux enregistré (
rechercher(terme),obtenirArticle(id)), typée à partir des corps de réponse observés. - Les éléments d'authentification (cookies, jetons porteur) se chargent à partir d'un fichier ou d'une variable d'environnement, avec une erreur claire invitant l'utilisateur à relancer la connexion navigateur lorsqu'ils expirent.
- Reproduisez les en-têtes que l'API requiert réellement — certains sites renvoient une erreur 403 sans un
user-agent,refereroux-requested-withcorrespondant. - Conservez les paramètres de pagination, tri et filtre qui sont apparus dans les chaînes de requête enregistrées comme options de fonction.
5. Vérifier
Appelez chaque fonction générée contre l'API réelle et comparez la forme de la réponse avec l'enregistrement. Problèmes courants :
| Symptôme | Cause | Correction |
|---|---|---|
| 401/403 | Session expirée ou manquante | Reconnectez-vous via agent-browser, réexportez les cookies |
| 403/419 sur les écritures | Le jeton CSRF est par session ou par formulaire | Récupérez d'abord l'endpoint du jeton, ou gardez ce flux avec navigateur |
| Fonctionne puis se casse | Paramètres de requête signés/expirants | Revenez au navigateur pour cette étape ; dérivez le reste |
| Forme différente du HAR | Tests A/B ou réponses dépendant de la géolocalisation | Réenregistrez et traitez l'union comme des champs optionnels |
Mises en garde
- Les API internes ne sont pas versionnées et changent sans préavis — gardez le HAR pour pouvoir redériver le client.
- Respectez les conditions d'utilisation du site et les limites de débit ; ajoutez des délais pour les récupérations en masse.
- Les fichiers HAR contiennent des identifiants de session en direct (cookies, jetons, corps POST). Traitez-les comme des secrets : ne les mettez pas dans le contrôle de version et supprimez-les une fois terminé.