Comment importer des fichiers HAR dans Apidog : transformer le trafic capturé en endpoints API

Vous avez vu une application effectuer une requête dans le navigateur. Ça marche. Les données sont là, dans l'onglet Réseau. Maintenant, vous voulez que ce même appel soit un point de terminaison documenté que vous pouvez enregistrer, simuler et tester, sans avoir à retaper manuellement l'URL, les en-têtes et le corps JSON.

Cet écart entre « le trafic que je peux voir » et « un point de terminaison que je peux réutiliser » est ce qu'un fichier HAR comble. Votre navigateur enregistre déjà chaque requête et réponse qu'il effectue. Exportez cet enregistrement, donnez-le à Apidog, et chaque appel capturé devient un véritable point de terminaison dans votre projet. Ce guide vous accompagne sur tout le chemin : capturer un fichier HAR dans les Outils de développement Chrome, l'importer avec les bonnes options, et nettoyer les points de terminaison générés pour que la liste reste utile. Pour un aperçu plus large des flux de travail de capture, notre guide sur les outils de capture de paquets avec Apidog couvre le sujet connexe.

Vous pouvez Télécharger Apidog gratuitement et suivre le guide sur les mêmes écrans.

Qu'est-ce qu'un fichier HAR et pourquoi il est important de conserver le trafic capturé

HAR signifie HTTP Archive. Selon la documentation d'Apidog, un fichier .har est « un fichier au format JSON utilisé pour enregistrer l'interaction d'un navigateur web avec un site. Il enregistre les requêtes web, les réponses, les en-têtes et d'autres données échangées entre le navigateur et le serveur. »

En clair : un fichier HAR est une transcription complète d'une session de navigation. Chaque GET, chaque POST, les en-têtes de requête, les corps de réponse, la synchronisation. Comme il s'agit de JSON, il se transfère facilement. Vous pouvez l'envoyer par e-mail, le joindre à un rapport de bogue ou le fournir à un outil capable de le lire.

Ce dernier point explique son importance ici. Une session capturée est un enregistrement de la façon dont une API se comporte réellement en production, et non de la façon dont une spécification indique qu'elle devrait le faire. Lorsque vous transformez cet enregistrement en points de terminaison, vous obtenez quelques avantages gratuitement :

• Une forme de requête réelle. L'URL exacte, les paramètres de requête, les en-têtes et le corps envoyés par l'application, pas une supposition.
• Une réponse réelle. Le code d'état et la charge utile renvoyés par le serveur, que vous pouvez utiliser comme simulation ou comme assertion de test.
• Un point de départ pour la documentation. Une API interne non documentée devient un ensemble de points de terminaison nommés que vous pouvez annoter.

C'est utile lorsque vous héritez d'un service sans spécification OpenAPI, lorsque vous faites de la rétro-ingénierie pour comprendre comment un widget tiers communique avec son backend, ou lorsque vous voulez reproduire un bogue avec l'appel exact qui l'a déclenché.

Étape 1 : capturer le fichier HAR dans les Outils de développement de votre navigateur

La capture se fait dans votre navigateur, et non dans Apidog. Chrome et Edge utilisent tous deux les mêmes Outils de développement, les étapes sont donc identiques. Disons que vous souhaitez capturer le trafic derrière une page d'historique de commandes.

1. Ouvrez la page que vous souhaitez enregistrer. Connectez-vous d'abord si l'API nécessite une session, car le fichier HAR inclura également ces requêtes.
2. Ouvrez les Outils de développement. Appuyez sur F12, ou Ctrl+Maj+I sur Windows et Linux, ou Cmd+Option+I sur Mac.
3. Basculez vers l'onglet Réseau. C'est là que les Outils de développement répertorient chaque requête effectuée par la page.
4. Actualisez la page, ou cliquez sur les actions dont vous voulez capturer le trafic. Le chargement de la vue de l'historique des commandes déclenche les appels vers /api/orders, /api/orders/{id}, et tout ce dont la page a besoin. Chacun apparaît comme une ligne.
5. Faites un clic droit sur n'importe quelle ligne de requête et choisissez Enregistrer tout au format HAR avec contenu. Choisissez un emplacement et enregistrez le fichier, par exemple order-history.har. Si la terminologie du menu vous déroute, la référence du panneau Réseau des Outils de développement Chrome documente le même flux de capture et d'exportation.

La partie « avec contenu » est importante. Elle indique aux Outils de développement d'inclure les corps de réponse, et pas seulement les métadonnées de la requête. Sans eux, vos points de terminaison importés auraient des formes de requête mais pas d'exemples de réponses.

Une vérification rapide avant de quitter le navigateur : si vous ouvrez le fichier .har dans un éditeur de texte, c'est du JSON lisible. Vous verrez un tableau entries où chaque entrée a un objet request et un objet response. C'est la structure qu'Apidog lit.

Une chose à garder à l'esprit. Un chargement de page contient plus que des appels d'API. Il récupère également des images, des feuilles de style et des scripts, et chacun d'eux se retrouve dans le fichier HAR. Vous n'avez pas besoin de les filtrer dans le navigateur ; Apidog vous offre une option pour les exclure lors de l'importation, ce qui sera abordé ensuite.

Étape 2 : importer le fichier HAR dans Apidog

Une fois le fichier enregistré, passez à Apidog. L'importateur se trouve au même endroit.

1. Ouvrez votre projet et allez dans Paramètres > Importer des données > Manuel.
2. Sélectionnez HAR comme format.
3. Téléchargez votre fichier .har, par exemple le order-history.har que vous avez enregistré il y a un instant.

Avant de confirmer, Apidog affiche trois options d'importation. Elles déterminent la propreté du résultat, il est donc utile de comprendre chacune d'elles plutôt que de simplement cliquer.

Option 1 : gestion de l'URL de base (BaseURL)

Chaque requête capturée possède une URL complète, comme https://api.shop.example.com/v1/orders/123. Vous avez deux choix concernant la partie hôte :

• Coder en dur (Hardcode) conserve l'URL de base (BaseURL) dans le chemin de chaque point de terminaison. Chaque point de terminaison porte le préfixe complet https://api.shop.example.com.
• Supprimer (Recommandé) supprime l'URL de base de sorte que le chemin du point de terminaison devienne /v1/orders/123. L'hôte est alors géré globalement via des variables d'environnement.

Choisissez l'option Supprimer, sauf si vous avez une raison de ne pas le faire. C'est le paramètre recommandé pour une raison : lorsque l'URL de base réside dans une variable d'environnement, vous pouvez pointer les mêmes points de terminaison vers la production, la pré-production ou un serveur local en changeant d'environnement, sans modifier les points de terminaison eux-mêmes. Le codage en dur lie chaque point de terminaison à l'hôte à partir duquel vous l'avez capturé, ce qui devient problématique dès que vous devez tester sur un serveur différent.

Option 2 : exclusion des ressources statiques

C'est l'interrupteur qui vous évite une liste de points de terminaison encombrée. L'option Ressource Statique, définie sur Exclure, indique à Apidog d'ignorer les images, les fichiers CSS et JavaScript capturés. Un seul chargement de page peut en produire des dizaines, et aucun d'entre eux n'est un point de terminaison API que vous souhaitez documenter.

Activez Exclure pour presque toutes les importations. Ce qui reste après le filtre est le trafic API réel : les appels JSON vers /api/orders et consorts, et non la requête pour logo.png.

Option 3 : génération d'un cas de test par point de terminaison

La troisième option est la Génération de cas de point de terminaison. Activez-la (ON) et Apidog créera un cas de test par défaut pour chaque point de terminaison lors de l'importation. Un cas de test est une invocation enregistrée et exécutable du point de terminaison avec les valeurs capturées déjà renseignées.

C'est une petite étape qui s'avérera payante plus tard. Si votre objectif est de tester ces points de terminaison, avoir un cas prêt par point de terminaison signifie que vous pouvez en exécuter un immédiatement au lieu de le construire à partir de zéro. Si vous ne souhaitez que de la documentation pour l'instant, vous pouvez le désactiver et ajouter des cas plus tard.

Confirmez l'importation. Apidog lit le fichier HAR, applique vos options et convertit les interactions du navigateur capturées en points de terminaison API au sein de votre projet. Ouvrez l'arborescence des points de terminaison et vous les verrez regroupés et prêts.

Voici à quoi ressemble approximativement un point de terminaison importé une fois qu'il est en place, en utilisant l'appel de commande comme exemple :

GET /v1/orders/123
Host: api.shop.example.com
Authorization: Bearer <token-from-capture>
Accept: application/json

Et la réponse capturée qu'Apidog stocke à ses côtés :

{
  "id": 123,
  "status": "shipped",
  "total": 48.5,
  "currency": "USD",
  "items": [
    { "sku": "TSHIRT-BLK-M", "qty": 2, "price": 19.25 }
  ],
  "createdAt": "2026-07-14T09:31:00Z"
}

Cette réponse est une donnée réelle renvoyée par le serveur, ce qui en fait une base solide pour une simulation ou une assertion de test.

Étape 3 : nettoyer les points de terminaison générés

Une importation HAR est une première passe rapide, pas une définition d'API finie. Le trafic capturé est naturellement désordonné, alors prévoyez quelques minutes pour ranger le résultat.

• Éliminer le bruit. Même avec Ressource Statique réglée sur Exclure, vous pourriez trouver des pings d'analyse, des vérifications de santé ou des appels tiers dont vous ne vous souciez pas. Supprimez les points de terminaison que vous n'utiliserez pas afin que l'arborescence reflète votre API réelle.
• Renommer et grouper. Les points de terminaison capturés sont nommés d'après leurs chemins, ce qui est fonctionnel mais plat. Donnez-leur des noms clairs (« Obtenir la commande par ID » au lieu de /v1/orders/123) et organisez-les en dossiers qui correspondent à la structure de votre API.
• Corriger les paramètres de chemin. Une capture de /v1/orders/123 est importée comme un chemin littéral. Si 123 est réellement un ID de commande, modifiez le point de terminaison pour que ce segment devienne un paramètre de chemin {orderId}. Ce seul changement transforme un appel capturé unique en un point de terminaison réutilisable qui fonctionne pour n'importe quelle commande.
• Nettoyer les secrets avant de partager. C'est facile à oublier. Votre fichier HAR a capturé tout jeton d'authentification actif pendant cette session, et il s'est retrouvé dans les en-têtes. Avant de valider le projet ou de le partager avec des coéquipiers, déplacez les jetons dans des variables d'environnement et supprimez-les des exemples. La documentation Stripe insiste sur le même point : ne jamais laisser les clés réelles fuir dans des artefacts partagés, et un fichier HAR est exactement le genre d'artefact qui les fait fuir.
• Vérifier la validité des corps. Si un corps est vide là où vous vous attendiez à des données, vous avez probablement exporté sans l'option « avec contenu ». Recapturez en utilisant Enregistrer tout au format HAR avec contenu et réimportez.

Une fois les points de terminaison nettoyés, ils se comportent comme n'importe quel autre point de terminaison dans Apidog. Vous pouvez les documenter, générer une simulation à partir de chaque réponse et construire des tests. Le guide pour écrire un scénario de test dans Apidog prend naturellement le relais à partir d'ici, et si vous souhaitez un code client typé à partir de ces points de terminaison, consultez comment générer du code client avec Apidog.

Variations et limites franches

Quelques situations se présentent assez souvent pour être signalées.

Il n'y a pas encore d'enregistreur automatique

Vous pourriez vous attendre à ce qu'Apidog s'exécute en arrière-plan et enregistre le trafic en direct, comme le ferait un proxy. Ce n'est pas le cas, et il est important d'être clair à ce sujet. La documentation indique clairement : « Apidog ne prend pas actuellement en charge la fonction d'enregistrement automatique des points de terminaison, mais il est prévu de la prendre en charge à l'avenir. »

Ainsi, le chemin pris en charge aujourd'hui est exactement celui de ce guide : capturez avec les Outils de développement de votre navigateur, exportez le fichier HAR et importez-le. Le flux recommandé décrit dans la documentation est d'ouvrir les Outils de développement pendant que vous utilisez un point de terminaison dans le navigateur, d'exporter le fichier HAR une fois terminé, de l'importer dans Apidog en un clic, puis de créer un scénario de test et d'importer toutes les requêtes pour la relecture. C'est une étape de capture manuelle suivie d'une importation en un clic, et non un enregistreur en direct. Lorsque la fonction d'enregistrement automatique sera disponible, cette section changera, mais n'attendez pas après elle.

L'extension de navigateur Apidog est un outil différent

Il existe une extension de navigateur Apidog, et il est facile de supposer qu'elle capture le trafic HAR. Ce n'est pas le cas. L'extension vous permet d'utiliser les fonctions de test et de débogage d'API d'Apidog directement dans le navigateur sans ouvrir le client de bureau. Il s'agit d'exécuter des requêtes, pas de les enregistrer.

La capture HAR provient des propres Outils de développement de votre navigateur, point final. Si vous utilisez l'extension pour les tests, sachez que le navigateur lui impose des limites : elle bloque certains en-têtes comme Cookie, Host, Origin et Content-Length, elle n'enverra pas de corps sur les requêtes GET ou HEAD, et elle ne peut pas atteindre le code local ou une base de données derrière votre machine. Pour capturer le trafic à importer, utilisez les Outils de développement et l'exportation HAR. Pour un débogage plus poussé nécessitant un contrôle total des en-têtes, le client de bureau Apidog n'a pas de telles limites imposées par le navigateur.

D'autres formats s'importent de la même manière

HAR est l'un des nombreux formats acceptés par le même écran Paramètres > Importer des données > Manuel. Si vous avez déjà un fichier OpenAPI ou Swagger, l'importer vous donne un résultat plus propre qu'une capture, car une spécification est structurée à dessein. Notre guide sur la migration de la documentation API Swagger vers Apidog couvre cette voie, et si vous venez de Postman, le guide de migration des environnements et collections Postman le fait également. Optez pour HAR lorsqu'une spécification réelle n'existe pas et que le trafic capturé est le meilleur enregistrement dont vous disposez.

Automatiser le flux de travail avec l'interface de ligne de commande Apidog (CLI)

L'importation d'un fichier HAR n'a pas besoin d'être une étape graphique. L'interface de ligne de commande Apidog (CLI) dispose d'une commande import qui lit directement un fichier HAR, ce que vous voulez lorsque la capture se produit sur un serveur, lorsque vous scripté l'importation dans un pipeline, ou lorsque vous laissez un agent de codage IA transformer une capture en points de terminaison :

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

# Transformer un fichier HAR capturé en points de terminaison dans votre projet
apidog import --project <PROJECT_ID> --format har --file ./capture.har

Le flag --format accepte également openapi, postman, wsdl, insomnia, et d'autres, de sorte qu'une seule commande couvre la plupart des sources d'importation. Une fois les points de terminaison créés et enregistrés dans un scénario de test, exécutez ce scénario sans interface graphique en intégration continue (CI) :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> -e <ENV_ID> -r cli

Ici, -t est l'ID du scénario de test enregistré, -e est l'ID de l'environnement (les mêmes variables d'environnement qui contiennent votre BaseURL), et -r sélectionne le rapporteur, cli pour la sortie console. Construisez le scénario avec le guide pour écrire un scénario de test dans Apidog, puis intégrez les deux commandes dans votre pipeline avec le guide CI/CD de l'interface de ligne de commande Apidog.

FAQ

Quels navigateurs peuvent exporter un fichier HAR ?

Tout navigateur basé sur Chromium avec les Outils de développement le fait de la même manière, donc Chrome et Edge utilisent tous deux l'onglet Réseau et l'élément de menu Enregistrer tout au format HAR avec contenu. La documentation Apidog couvre spécifiquement la procédure pour Chrome et Edge. D'autres navigateurs ont leurs propres menus d'exportation, mais l'intitulé peut différer, alors adaptez-vous à la terminologie des Outils de développement de votre navigateur.

Ma liste de points de terminaison importés est énorme. Qu'est-ce qui n'a pas fonctionné ?

Vous avez très probablement laissé l'option Ressource Statique configurée pour inclure tout. Un chargement de page récupère des images, du CSS et des scripts, et tous se retrouvent dans le fichier HAR. Réimportez le fichier avec l'option Ressource Statique réglée sur Exclure, et la liste se réduira aux appels API réels. Vous pouvez également supprimer les éléments restants manuellement par la suite.

Dois-je choisir Coder en dur ou Supprimer pour l'URL de base (BaseURL) ?

Choisissez Supprimer (Recommandé) dans presque tous les cas. Cela retire l'hôte de chaque chemin de point de terminaison afin que vous puissiez le gérer globalement via une variable d'environnement, ce qui vous permet de basculer entre la production, la pré-production et le local sans modifier les points de terminaison. Cette même configuration est ce qu'un scénario de test dans Apidog lit lors de son exécution. Ne choisissez Coder en dur que si vous souhaitez spécifiquement que l'URL complète soit intégrée à chaque chemin.

Le fichier HAR inclut-il mes jetons d'authentification ?

Oui, et c'est là le piège. Un fichier HAR enregistre les en-têtes réels envoyés pendant la session, donc tout jeton porteur ou cookie actif se trouve dans le fichier. Traitez un fichier HAR comme un secret : ne le collez pas dans un problème public, et après l'importation, déplacez les identifiants dans des variables d'environnement et supprimez-les des exemples enregistrés avant de partager le projet.

Puis-je ignorer l'interface graphique et importer un fichier HAR depuis la ligne de commande ?

Oui. La commande apidog import --project <id> --format har --file <path> de l'interface de ligne de commande Apidog importe un fichier HAR dans votre projet sans ouvrir l'application, ce qui est idéal lorsque la capture se produit sur un serveur ou dans une tâche d'intégration continue (CI). L'interface graphique vous offre toujours les options d'importation interactives (gestion de l'URL de base, filtrage des ressources statiques) pour une capture ponctuelle, alors choisissez ce qui vous convient le mieux : la CLI pour les importations scriptées ou pilotées par agent, l'interface graphique lorsque vous souhaitez ajuster l'importation manuellement. Après l'importation, apidog run rejoue les scénarios de test que vous avez construits à partir de ces points de terminaison.

En résumé

Un fichier HAR est le pont entre le trafic que vous pouvez voir et les points de terminaison que vous pouvez réutiliser. Capturez la session dans les Outils de développement de votre navigateur avec Enregistrer tout au format HAR avec contenu, importez-la via Paramètres > Importer des données > Manuel avec l'option Supprimer pour l'URL de base et Ressource Statique réglée sur Exclure, puis passez quelques minutes à renommer, paramétrer et nettoyer les secrets. Ce que vous obtenez est un ensemble de points de terminaison fonctionnels que vous pouvez documenter, simuler et tester.

Prêt à transformer votre prochaine capture en véritables points de terminaison ? Téléchargez Apidog et essayez-le gratuitement, aucune carte de crédit requise.