Comment gérer les environnements et variables secrètes dans Apidog (Dev, Staging, Prod)

Chaque équipe API se heurte au même problème. Les premières requêtes que vous construisez pointent vers un seul serveur, avec un seul jeton collé dans un en-tête. Puis l'environnement de staging apparaît. Puis la production. Soudain, vous modifiez les URL à la main avant chaque exécution, et quelqu'un teste un point de terminaison de suppression contre la production parce qu'une URL de base était obsolète. Les variables d'environnement API existent pour éliminer toute cette catégorie d'erreurs, et Apidog les intègre au cœur du produit plutôt que de les ajouter après coup.

Ce guide vous montre comment configurer des environnements de développement (dev), de staging et de production (prod) dans Apidog, stocker les jetons et les clés API comme variables au lieu de chaînes de caractères codées en dur, garder les vrais secrets hors du cloud grâce aux valeurs locales, et transmettre les environnements au CI via l'interface en ligne de commande (CLI) d'Apidog. Si vous souhaitez une vue d'ensemble de ce qu'un client API avec gestion des environnements et des secrets devrait prendre en charge, nous l'avons traité séparément. Ici, nous passons à la pratique.

Pourquoi les URL et les jetons codés en dur posent problème avec un deuxième environnement

Avec un seul environnement, le codage en dur fonctionne bien. https://api.acmepay.dev figure dans chaque requête, votre jeton est dans chaque en-tête d'autorisation, et rien ne pose problème pour l'instant.

Les problèmes commencent dès qu'un deuxième environnement apparaît :

• Chaque requête doit être modifiée pour cibler un nouvel environnement. Cinquante points de terminaison pointant vers le développement signifient cinquante modifications d'URL pour tester le staging, puis cinquante autres pour revenir en arrière. Vous en manquerez une.
• Les jetons fuient au-delà des limites. Une clé API de production collée dans un corps de requête est enregistrée avec le projet, partagée avec l'équipe et exportée avec la collection. La méthodologie de l'application Twelve-Factor est catégorique à ce sujet : la configuration varie entre les déploiements, le code non, donc la configuration n'a jamais sa place dans l'artefact que vous partagez.
• Les exécutions ne sont plus reproductibles. Lorsque l'URL et les identifiants vivent à l'intérieur de chaque requête, « exécuter les tests de fumée sur le staging » devient un rituel manuel de recherche et remplacement au lieu d'un basculement en un clic.

La solution est ancienne et éprouvée : séparer la définition de la requête (méthode, chemin, corps, assertions) du contexte de déploiement (URL de base, identifiants, ID spécifiques à l'environnement). Les requêtes restent identiques partout. Seul le contexte change.

Comment Apidog modélise les environnements et les variables

Apidog divise le problème en deux parties qui fonctionnent ensemble.

Un **environnement** est un contexte nommé, comme Dev, Staging ou Prod. Chaque environnement possède sa propre URL de base (le serveur vers lequel les requêtes sont envoyées) et son propre ensemble de valeurs de variables. Changez d'environnement et chaque requête du projet se recible instantanément, comme le décrivent les documents de gestion des environnements.

Une **variable** est un espace réservé nommé que vous référencez comme {{variable_name}} partout où une valeur est attendue : URL, paramètres de requête, en-têtes, corps de requête et scripts. Lors de l'exécution, Apidog résout l'espace réservé par rapport à l'environnement actif et aux autres portées en jeu.

Portées des variables et celle qui l'emporte

Apidog résout les variables à travers cinq portées. De la priorité la plus basse à la plus haute : globale, module, environnement, données et locale.

L'ordre de priorité est important en pratique. Définissez {{auth_token}} comme valeur de repli globale et cela fonctionnera partout, mais dès que votre environnement Staging définit son propre {{auth_token}}, la valeur de l'environnement l'emporte tant que Staging est actif. C'est exactement ce que vous voulez : des valeurs par défaut partagées en bas, des remplacements spécifiques à l'environnement au-dessus. Pour une présentation plus approfondie de chaque portée, consultez notre guide sur la maîtrise des variables dans Apidog.

Un comportement qui déroute les utilisateurs : les variables locales sont temporaires par conception. Si vous en définissez une dans un script, elle disparaît une fois l'exécution terminée. C'est une fonctionnalité pour les valeurs temporaires au sein d'un scénario de test, et une erreur dans votre modèle mental si vous vous attendiez à ce qu'elle persiste. Tout ce dont vous avez besoin pour demain doit être placé dans une variable d'environnement ou globale.

Configurer dev, staging et prod dans Apidog

Voici le flux de travail pour une API de paiement avec trois déploiements.

1. Créer les trois environnements

Ouvrez la gestion des environnements depuis le coin supérieur droit du projet et créez un nouvel environnement pour chaque déploiement. Donnez à chacun un nom et une URL de base :

• Dev → https://api-dev.acmepay.dev
• Staging → https://api-staging.acmepay.dev
• Prod → https://api.acmepay.com

Gardez les URL de base préfixées par le protocole et sans barre oblique finale, afin que les chemins se concatènent proprement.

2. Définir les mêmes noms de variables dans chaque environnement

La cohérence est tout le secret. Chaque environnement définit les mêmes noms de variables avec des valeurs différentes :

3. Référencer les variables dans les requêtes, jamais les valeurs brutes

Une requête pour créer un paiement ressemble désormais à ceci partout :

POST /v1/charges
Authorization: Bearer {{auth_token}}

{
  "merchant_id": "{{merchant_id}}",
  "amount": 1999,
  "currency": "usd"
}

L'URL de base n'apparaît pas du tout ; Apidog préfixe automatiquement l'URL de base de l'environnement actif. Rien dans la définition de la requête ne nomme un environnement, ce qui la rend portable.

4. Basculer avec le sélecteur

Le sélecteur d'environnement se trouve dans le coin supérieur droit de la fenêtre Apidog. Choisissez Staging et chaque requête, scénario de test et script du projet se résoudra par rapport à l'URL de base et aux valeurs des variables de l'environnement de staging. Pas d'édition, pas de recherche et remplacement. Si vous évaluez ce qui devrait se trouver dans quel niveau de déploiement, notre comparaison des environnements de bac à sable vs. de test explique comment les équipes les divisent généralement.

Vous venez de Postman ? Vos environnements existants sont transférés. Le guide de migration Postman explique comment importer des collections et des environnements en quelques clics, valeurs de variables incluses.

Gardez les secrets locaux : valeurs partagées vs valeurs locales

C'est la partie que la plupart des équipes gèrent mal, et celle où la conception d'Apidog prend tout son sens.

Chaque variable d'environnement et variable globale dans Apidog peut contenir deux valeurs, comme documenté dans la référence des variables :

• Valeur partagée : synchronisée avec les serveurs d'Apidog et visible par tous les membres du projet.
• Valeur locale : stockée uniquement dans le cache de votre client sur votre machine. Elle n'est jamais synchronisée avec le cloud et les membres de l'équipe ne la voient jamais.

Lorsque les deux existent, votre client utilise la valeur locale. Le modèle sécurisé pour les secrets est donc simple :

1. Créez la variable, par exemple {{auth_token}}, dans chaque environnement.
2. Laissez la valeur partagée vide, ou définissez-la comme un espace réservé tel que SET_LOCALLY.
3. Placez le vrai jeton dans la valeur locale sur votre propre machine.

La structure des variables est synchronisée avec l'équipe. Le secret ne l'est pas. Chaque ingénieur saisit ses propres identifiants une seule fois, et chaque requête partagée fonctionne immédiatement pour lui. Cela correspond à la feuille de triche de gestion des secrets de l'OWASP : limitez strictement la portée des secrets, partagez-les via des canaux contrôlés et tenez-les éloignés de tout ce qui est largement répliqué.

Deux mises en garde importantes. Les valeurs locales résident dans le cache du client, donc effacer le cache d'Apidog les supprime, et passer à un nouvel ordinateur portable signifie les ressaisir. Prévoyez cinq minutes pour cela, pas cinq heures d'examen d'incident parce qu'une clé de production a été synchronisée avec douze personnes.

Vous pouvez également marquer un environnement entier comme privé au lieu de partagé. Un environnement Prod visible uniquement par les deux personnes qui déploient est une configuration légitime, et cela s'ajoute aux valeurs locales pour une défense en profondeur.

Utiliser les environnements dans les scénarios de test et le CI

Les environnements s'intègrent directement dans les scénarios de test d'Apidog. Construisez un scénario une fois (créer un paiement, interroger le statut, affirmer le règlement), puis choisissez l'environnement sur lequel l'exécuter au moment de l'exécution. Le même scénario devient votre test de fumée de développement et votre suite de régression de staging.

Les scripts lisent et écrivent dans les mêmes portées. Un post-processeur qui capture un nouveau jeton à partir d'une réponse de connexion ressemble à ceci :

const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);

Les requêtes ultérieures dans le scénario résolvent {{auth_token}} à la valeur capturée. Pour des modèles comme l'intégration de paramètres de requête dans des scripts, consultez la récupération des paramètres de requête dans les scripts pré/post-requête.

Pour le CI, l'interface en ligne de commande (CLI) d'Apidog prend l'environnement comme un drapeau :

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  --env-var "auth_token=$STAGING_API_TOKEN"

-e sélectionne l'environnement par ID. Notez que l'interface en ligne de commande (CLI) résout les valeurs partagées, et non les valeurs locales de votre machine, ce qui est le comportement correct : vos secrets personnels ne devraient de toute façon pas être accessibles depuis un agent de build. Injectez plutôt les vrais identifiants à l'exécution, avec les surcharges --env-var et --global-var sous la forme clé=valeur, ou --variables pour charger un fichier entier. Stockez les secrets réels dans le magasin de secrets de votre fournisseur CI (secrets GitHub Actions, variables GitLab CI) et transmettez-les. Le pipeline ne contient jamais de jeton en texte brut, et la rotation d'un identifiant signifie la mise à jour d'un seul secret CI.

Le flux de travail d'équipe qui en découle

Mis ensemble, la division du travail est claire :

• Partagé, synchronisé : noms d'environnement, URL de base, noms de variables, valeurs partagées de remplacement, scénarios de test.
• Personnel, local : les jetons et clés de chaque ingénieur en tant que valeurs locales.
• Détenu par le CI : identifiants du pipeline dans le magasin de secrets du CI, injectés via des drapeaux CLI.

Un nouveau coéquipier rejoint l'équipe, ouvre le projet et voit trois environnements prêts à l'emploi avec chaque variable nommée et documentée. Il colle son propre jeton de développement dans un champ de valeur locale et commence à travailler. Personne n'envoie de clé de production par message direct. Personne ne maintient une page wiki « URL de staging actuelle » qui devient obsolète.

Pièges courants à éviter

• Commitre de vrais jetons dans les valeurs partagées. L'erreur la plus courante de loin. Si un secret doit parvenir aux membres de l'équipe, il passe par un gestionnaire de mots de passe ou un coffre-fort, et non par une variable synchronisée. Vérifiez vos valeurs partagées une fois ; tout ce qui ressemble à un identifiant actif doit être déplacé vers les valeurs locales et être renouvelé.
• Oublier quel environnement est actif. La mémoire musculaire envoie des requêtes avant que les yeux ne vérifient le sélecteur. Rendez les opérations destructives plus difficiles à déclencher par erreur : gardez Prod privé pour moins de personnes, et donnez aux variables spécifiques à la production des noms distincts ou des valeurs partagées de remplacement afin qu'une exécution dans le mauvais environnement échoue bruyamment sur l'authentification au lieu de réussir discrètement.
• S'attendre à ce que les variables temporaires persistent. Les variables de portée locale définies pendant une exécution disparaissent lorsque celle-ci se termine. Promouvez explicitement tout élément durable à la portée de l'environnement dans votre script.
• Des noms de variables différents d'un environnement à l'autre. Si le dev l'appelle {{token}} et le staging l'appelle {{auth_token}}, changer d'environnement perturbera la moitié de vos requêtes. Mêmes noms partout, valeurs différentes seulement.
• Un seul environnement géant pour tout. Si vous entassez dev_base_url et prod_base_url dans un seul environnement, vous avez recréé le problème du codage en dur avec des étapes supplémentaires. Un environnement par contexte de déploiement.

Prêt à configurer cela ? Téléchargez Apidog gratuitement, créez vos trois environnements et déplacez votre premier jeton vers une valeur locale. Cela prend environ dix minutes pour un projet existant.

FAQ

Comment puis-je empêcher les secrets d'être partagés dans les projets Apidog ?

Stockez-les comme valeurs locales. Chaque variable possède une valeur partagée (synchronisée avec l'équipe) et une valeur locale (mise en cache uniquement sur votre machine). Laissez la valeur partagée comme un espace réservé et gardez le vrai jeton en local. Pour une isolation supplémentaire, marquez les environnements sensibles comme Prod comme privés afin que seules des personnes spécifiques les voient.

Quelle est la différence entre les variables globales et d'environnement ?

Les variables globales s'appliquent à l'ensemble du projet, quel que soit l'environnement actif ; utilisez-les pour les valeurs qui ne changent jamais entre les déploiements, comme une chaîne de version d'API. Les variables d'environnement appartiennent à un seul environnement et l'emportent sur les globales lorsque les deux définissent le même nom. Notre guide des variables détaille les cinq portées, y compris le module, les données et le local.

Pourquoi mon test réussit-il dans le client Apidog mais échoue-t-il en CI ?

Généralement parce que le client résout les valeurs locales tandis que l'interface en ligne de commande (CLI) résout les valeurs partagées. Si votre jeton ne se trouve que dans une valeur locale, la CLI voit une variable vide ou de remplacement. Passez l'identifiant explicitement dans le pipeline avec --env-var "auth_token=$YOUR_CI_SECRET" afin que le CI fournisse son propre secret lors de l'exécution.

Puis-je transférer mes environnements Postman vers Apidog ?

Oui. Apidog importe directement les collections et les environnements Postman, en conservant les noms et les valeurs des variables intacts, de sorte que vos références {{base_url}} continuent de fonctionner après la migration. Examinez les valeurs importées par la suite et déplacez tous les identifiants réels vers des valeurs locales, car les exportations Postman peuvent contenir des secrets en texte clair.