Vous avez quarante endpoints et chacun doit envoyer les en-têtes Authorization: Bearer ... et X-Api-Version. Les ajouter manuellement à chaque requête est lent et source d'erreurs : un endpoint reçoit le jeton, un autre l'oublie, puis vous cherchez une erreur 401 sur quelques routes seulement.
Essayez Apidog dès aujourd’hui
Avec Apidog, définissez ces valeurs une seule fois au niveau du projet. Chaque requête les hérite automatiquement, tout en laissant la possibilité à un endpoint spécifique de fournir sa propre valeur. Ce guide montre comment combiner :
- les paramètres globaux pour les en-têtes communs ;
- les variables d'environnement pour les secrets ;
- un script de pré-requête pour limiter un en-tête à un dossier.
Pour aller plus loin sur les variables, consultez le guide sur la maîtrise des variables dans Apidog.
L'approche reprend le fonctionnement standard des en-têtes HTTP : des paires clé/valeur envoyées avec une requête. Apidog permet simplement de les déclarer une fois au lieu de les répéter endpoint par endpoint.
Ce que signifie « paramètre global »
Dans Apidog, un paramètre global s'applique à tout le projet plutôt qu'à une seule requête.
Vous pouvez déclarer des paramètres globaux à quatre emplacements :
-
En-têtes : pour
Authorization,X-Api-Version, etc. - Cookies : pour les cookies de session.
-
Requête : pour ajouter des paramètres tels que
?api_key=.... - Corps : pour injecter un champ dans les corps de requête.
Pour un jeton bearer, utilisez En-têtes.
Les paramètres définis directement sur un endpoint ont priorité sur les paramètres globaux. Un en-tête
Authorizationdéfini sur une requête remplace donc la valeur globale pour cette requête.
Cette précédence est utile : le paramètre global fournit une valeur par défaut, sans écraser les exceptions.
Ajouter des en-têtes globaux au projet
Objectif : ajouter Authorization et X-Api-Version à toutes les requêtes sans modifier les endpoints existants.
1. Ouvrir la gestion de l'environnement
Dans Apidog, ouvrez la Gestion de l'environnement depuis la partie supérieure droite de l'interface.
C'est l'emplacement où vous gérez les paramètres appliqués au projet. Consultez également la documentation Apidog pour la description des paramètres globaux.
2. Sélectionner les en-têtes
Choisissez la section En-têtes ou En-tête de Requête.
Pour un cookie, un paramètre d'URL ou un champ de corps, utilisez respectivement les sections Cookies, Requête ou Corps. Le principe reste le même.
3. Créer l'en-tête Authorization
Ajoutez un premier paramètre global :
| Champ | Valeur |
|---|---|
| Nom | Authorization |
| Type | Chaîne de caractères |
| Valeur par défaut | Bearer {{token}} |
| Description | Jeton Bearer pour tous les endpoints authentifiés. |
Ajoutez ensuite l'en-tête de version :
| Champ | Valeur |
|---|---|
| Nom | X-Api-Version |
| Type | Chaîne de caractères |
| Valeur par défaut | 2024-08-01 |
| Description | Version d'API fixée pour chaque requête. |
4. Activer les paramètres
Activez l'interrupteur situé à droite de chaque paramètre.
Vous pourrez ainsi désactiver temporairement un en-tête global pendant une session de débogage, sans supprimer sa configuration.
5. Enregistrer
Enregistrez la configuration.
Toutes les requêtes du projet enverront maintenant ces en-têtes, sauf lorsqu'un endpoint définit explicitement une valeur concurrente.
6. Vérifier la requête réellement envoyée
Ne vous contentez pas de supposer que la configuration fonctionne.
- Envoyez une requête du projet.
- Ouvrez l'onglet Requête Réelle dans la console de réponse.
- Vérifiez les en-têtes résolus.
Exemple :
GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Si les en-têtes apparaissent dans Requête Réelle, ils ont bien été envoyés sur le réseau.
Stocker le secret dans une variable
Évitez de mettre directement un jeton sensible dans la valeur par défaut d'un paramètre global.
Utilisez :
Bearer {{token}}
au lieu de :
Bearer sk_live_7f3a9c2e1b8d4056
Le schéma Bearer est défini par la RFC 6750, et la référence MDN de l'en-tête Authorization décrit son utilisation côté serveur.
Créer la variable token
- Cliquez sur l'icône d'environnement
≡en haut à droite. - Ouvrez la section Variables Globales.
- Créez une variable nommée
token. - Donnez-lui la valeur de votre secret bearer.
- Cliquez sur Enregistrer.
Lors de l'envoi, Apidog résout :
Bearer {{token}}
en :
Bearer <votre-vrai-secret>
L'onglet Requête Réelle permet de confirmer que la substitution a bien eu lieu.
Le modèle recommandé est donc :
- le paramètre global déclare l'emplacement de l'en-tête ;
- la variable contient la valeur sensible.
Pour approfondir ce sujet, consultez le guide sur la gestion de l'environnement et des secrets du client API.
Utiliser une valeur différente selon l'environnement
Les projets utilisent généralement des environnements distincts pour le développement, le test et la production.
Créez par exemple un token différent dans chaque environnement :
Développement → token de développement
Test → token de test
Production → token de production
Basculez ensuite d'environnement avec le menu déroulant Environnements, situé près de l'icône ≡.
L'en-tête global reste inchangé :
Authorization: Bearer {{token}}
Seule la valeur résolue change selon l'environnement actif.
Pour les flux bearer, clé API ou OAuth, consultez le guide des schémas de sécurité.
Ajouter un en-tête à un seul dossier
Les paramètres globaux s'appliquent à tout le projet. Si seuls les endpoints /admin ont besoin d'un en-tête X-Admin-Scope, utilisez un script de pré-requête au niveau du dossier.
Apidog ne propose pas de champ natif pour ajouter un en-tête directement dans les paramètres d'un dossier. Utilisez plutôt un script compatible pm.* :
pm.request.headers.add({
key: 'X-Admin-Scope',
value: 'full'
});
Ajoutez ce script comme script de pré-requête sur le dossier concerné.
Résultat :
- les requêtes du dossier reçoivent
X-Admin-Scope: full; - les requêtes hors du dossier ne reçoivent pas cet en-tête.
Utilisez cette solution pour les besoins limités à un dossier. Pour une valeur partagée par le projet, préférez les paramètres globaux.
Pour d'autres cas d'automatisation, consultez le guide des scripts de pré-requête et post-requête dans Apidog.
Choisir le bon mécanisme
| Besoin | Mécanisme |
|---|---|
| Ajouter un en-tête à toutes les requêtes | Paramètre global dans En-têtes |
| Stocker un jeton ou une clé sans le répéter | Variable d'environnement, par exemple {{token}}
|
| Ajouter un en-tête à un seul dossier | Script de pré-requête avec pm.request.headers.add()
|
Points à vérifier :
- évitez les noms de paramètres globaux en double ;
- utilisez le type de paramètre adapté ;
- vérifiez si un endpoint définit déjà son propre
Authorization; - contrôlez toujours le résultat dans Requête Réelle.
La documentation ne mentionne pas de restriction de plan pour les paramètres globaux, les variables d'environnement ou les scripts de pré-requête au niveau du dossier.
Automatiser les exécutions avec Apidog CLI
Les paramètres globaux et les variables d'environnement sont également utilisés pendant les exécutions automatisées.
Quand vous exécutez un scénario Apidog depuis la ligne de commande avec un identifiant d'environnement, les variables de cet environnement sont résolues de la même façon que dans l'interface. Votre en-tête :
Authorization: Bearer {{token}}
utilise donc automatiquement le jeton correspondant à l'environnement sélectionné.
Installez la CLI avec Node.js v16 ou plus récent :
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Exécutez ensuite un scénario contre un environnement donné :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Options utilisées :
-
-t: identifiant du scénario de test ; -
-e: identifiant de l'environnement ; -
-r: rapporteur, par exemplecli,htmloujunit.
Ainsi, vous définissez les en-têtes et les variables une seule fois, puis vous réutilisez la même configuration dans vos pipelines CI.
Consultez le guide d'installation de la CLI Apidog et l'intégration de la CLI Apidog dans GitHub Actions pour mettre en place un pipeline complet.
FAQ
Les paramètres globaux remplacent-ils les en-têtes définis sur un endpoint ?
Non. Les paramètres d'un endpoint ont priorité sur les paramètres globaux.
Si une requête définit déjà :
Authorization: Bearer autre-jeton
cette valeur est utilisée à la place de la valeur globale.
Où stocker le jeton réel ?
Stockez-le dans une variable d'environnement ou une variable globale.
Définissez l'en-tête global ainsi :
Bearer {{token}}
Puis stockez la valeur réelle dans token via l'icône d'environnement ≡.
Le guide sur l'extraction de variables avec JSONPath montre également comment récupérer un jeton depuis une réponse de connexion et le réutiliser.
Comment confirmer que l'en-tête a été envoyé ?
Envoyez une requête et ouvrez l'onglet Requête Réelle.
Il affiche les en-têtes et les variables après résolution. Si l'en-tête est visible dans cet onglet, il a été envoyé.
Puis-je limiter un en-tête à un dossier ?
Oui, avec un script de pré-requête sur ce dossier :
pm.request.headers.add({
key: 'X-Admin-Scope',
value: 'full'
});
Il n'existe pas d'interface native dédiée aux en-têtes de dossier.
Un plan payant est-il nécessaire ?
La documentation ne mentionne pas de restriction de niveau pour les paramètres globaux, les variables d'environnement ou les scripts de pré-requête au niveau du dossier.
En résumé
Pour envoyer les mêmes en-têtes à chaque requête :
- créez un paramètre global dans En-têtes ;
- utilisez une variable comme
{{token}}pour les secrets ; - vérifiez le résultat dans Requête Réelle ;
- utilisez un script de pré-requête si l'en-tête doit s'appliquer à un seul dossier.
Pour tester cette configuration dans votre projet, téléchargez Apidog et créez votre premier en-tête global.
Top comments (0)