Collections, variables et environnements

Ce que vous saurez faire

Utilisez une seule collection partout où l’API s’exécute : sur votre ordinateur maintenant, puis sur Internet après le module 7. Un seul menu permet de changer d’environnement. La clé d’API que vous ajouterez plus tard ne quittera jamais votre ordinateur.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 40 minutes

Ce que vous devez savoir

• La variable de collection baseUrl, présentée dans Premières requêtes dans Postman : faire fonctionner les requêtes importées.
• L’étape DNS, présentée dans Du navigateur au serveur : les bases : du nom au serveur : DNS.

Ce qu’il vous faut sur votre ordinateur

• L’application de bureau Postman, avec une session ouverte, comme dans Premières requêtes dans Postman : installer l’application et se connecter.
• La collection Ticket Classifier API, avec baseUrl défini à http://127.0.0.1:8000. Vous l’avez créée dans Premières requêtes dans Postman : Importer le document OpenAPI. Si elle manque, importez-la de nouveau comme dans cette section.
• Les trois requêtes d’échec dans la collection, créées dans Premières requêtes dans Postman : à vous de jouer : des requêtes pour chaque ligne.
• L’API s’exécute localement avec fastapi dev, comme dans Environnement et premier point de terminaison : étape 3 : démarrer le serveur.
• Si votre projet manque ou ne fonctionne plus, copiez l’instantané end-of-m04, qui correspond à la fin du module 4. Suivez les instructions dans Utiliser un instantané. Refaites ensuite la pratique guidée et la tâche « À vous de jouer » de Premières requêtes dans Postman.

Les étapes dans l’application suivent la documentation de Postman pour Postman 12.

Variables

Une variable est un nom, écrit {{name}}, que Postman remplace par une valeur juste avant d’envoyer une requête. Vous pouvez utiliser des variables dans l’URL, les en-têtes et le corps. Elles permettent d’utiliser la même requête avec différents serveurs et différentes clés, sans modifier la requête.

Postman conserve les variables à plusieurs niveaux, appelés portées. Ce cours en utilise deux :

Portée	Appartient à	Utilisation
Variable de collection	Une collection, pour tous les environnements	Valeurs identiques partout, ou valeur par défaut
Variable d’environnement Postman	Un environnement, comme « Local » ou « Deployed »	Valeurs qui changent selon l’endroit où l’API s’exécute : baseUrl, apiKey

Un environnement Postman est un ensemble nommé de variables, par exemple Local (local) avec baseUrl = http://127.0.0.1:8000. Un seul environnement est actif à la fois. (Il diffère d’une variable d’environnement dans le terminal et d’un environnement virtuel Python. Ce cours utilise toujours « environnement Postman » pour le désigner.)

Si l’environnement et la collection ont une variable du même nom, l’environnement l’emporte. Postman affiche la valeur de la collection barrée.

La requête reste identique. L'environnement Postman actif détermine sa destination et la clé qu'elle contient.

Description textuelle du diagramme

La requête de la collection est POST {{baseUrl}}/v1/classify, avec l’en-tête X-API-Key: {{apiKey}}. La collection possède sa propre valeur baseUrl, soit http://127.0.0.1:8000. L’environnement Postman actif, Deployed (déployé), contient aussi baseUrl, défini à https://ticket-api.example.dev. Cette valeur remplace celle de la collection. Il contient aussi apiKey, marquée sensible, avec une valeur locale seulement. Postman remplace les deux variables et envoie POST https://ticket-api.example.dev/v1/classify avec la vraie clé dans l’en-tête.

Valeurs locales et valeurs partagées

Postman conserve vos collections et environnements dans votre compte Postman, dans le nuage, pour permettre leur utilisation sur un autre ordinateur. Chaque variable possède deux valeurs :

Valeur	Synchronisée avec le nuage de Postman?	Utilisation
Valeur partagée	Oui. Toute personne avec qui vous partagez la collection ou l’environnement peut la voir.	Valeurs sans risque à partager : URL, identifiants d’exemple
Valeur locale	Non. Elle reste sur cet ordinateur.	Secrets : clés d’API, jetons (tokens), mots de passe

Postman envoie la valeur locale si elle existe. Pour un secret, laissez la valeur partagée vide et placez la vraie valeur uniquement dans la valeur locale. Marquez aussi la variable comme sensible avec l’icône de cadenas à côté de son nom. Postman masque alors la valeur à l’écran sous la forme ••••. Elle n’apparaît donc pas dans une capture ou un partage d’écran.

Exemple détaillé : deux environnements Postman

Amira crée un environnement pour son ordinateur et un autre pour l’API déployée qu’elle crée au module 7 :

1. Dans la barre latérale, sélectionnez Environments (environnements), puis l’icône + (ajouter). Nommez le nouvel environnement Local (local).
2. Ajoutez une variable baseUrl, avec la valeur http://127.0.0.1:8000.
3. Ajoutez une variable apiKey. Laissez sa valeur partagée vide. Marquez-la comme sensible avec l’icône de cadenas. (Le module 6 lui donne une valeur locale.)
4. Créez un deuxième environnement, Deployed (déployé), avec les deux mêmes variables. Pour baseUrl, utilisez https://ticket-api.example.dev pour le moment. Le module 7 vous donne la vraie URL.
5. Dans le sélecteur d’environnement, en haut à droite de la fenêtre, choisissez Local.

Elle configure ensuite la collection pour utiliser apiKey dans toutes les requêtes, une seule fois, au niveau de la collection :

1. Sélectionnez la collection et ouvrez son onglet Authorization (autorisation).
2. Définissez Auth Type (type d’authentification) à API Key (clé d’API).
3. Définissez Key (clé) à X-API-Key, Value (valeur) à {{apiKey}} et Add to (ajouter à) à Header (en-tête).
4. Enregistrez la collection.

Chaque requête de la collection utilise par défaut le type d’authentification Inherit auth from parent (hériter de l’authentification du parent). Elles envoient donc maintenant toutes l’en-tête. L’API l’ignore pour le moment. Le module 6 le rend obligatoire.

Elle envoie Classify a support ticket (classer un billet de soutien). Dans l’URL, elle place le pointeur sur {{baseUrl}}. Postman affiche la valeur de Local et la valeur barrée de la collection. Elle choisit ensuite Deployed dans le sélecteur et envoie de nouveau la requête. Elle échoue avec une erreur indiquant que l’hôte est introuvable. C’est normal : ticket-api.example.dev n’existe pas. La même requête est partie vers une autre destination, sans aucune modification.

Enregistrer des exemples pour les autres développeurs

Une collection sert aussi de documentation. Chaque requête peut conserver des exemples : des paires enregistrées contenant une requête et sa réponse. L’importation a créé des exemples à partir de votre document OpenAPI. Vous pouvez en ajouter des réels :

1. Envoyez Reject an empty subject (rejeter un sujet vide).
2. Dans le volet de réponse, sélectionnez Save Response (enregistrer la réponse), puis Save as example (enregistrer comme exemple).
3. Donnez un nom clair à l’exemple, comme 422 - empty subject (422 - sujet vide).

Un développeur qui ouvre la collection voit la réponse exacte pour chaque cas, sans rien envoyer.

Pratique guidée : des environnements pour votre collection

1. Créez les environnements Postman Local et Deployed, comme dans l’exemple détaillé, puis choisissez Local.
2. Dans l’onglet Variables (variables) de la collection, regardez baseUrl. Placez ensuite le pointeur sur {{baseUrl}} dans une requête et constatez que la valeur de l’environnement l’emporte.
3. Configurez Authorization dans la collection pour utiliser la clé d’API, comme dans l’exemple détaillé.
4. Envoyez chaque requête de la collection avec Local. Toutes donnent le code d’état prévu dans votre tableau de contrat.
5. Choisissez Deployed et envoyez Check that the service runs (vérifier que le service fonctionne). Lisez l’erreur et indiquez à quelle étape de Du navigateur au serveur : les bases la requête a échoué.
6. Choisissez de nouveau Local. Enregistrez un exemple pour le cas de réussite et un autre pour un cas d’échec.

Afficher la réponse à l’étape 5

La requête échoue à DNS, la première étape : l’hôte ticket-api.example.dev n’existe pas. Il n’y a donc aucune adresse IP à laquelle se connecter. Aucun code d’état n’est renvoyé, car aucun serveur n’a répondu.

À vous de jouer : un troisième environnement

Démarrez une deuxième copie de votre API sur un autre port, dans un nouveau terminal : fastapi dev ticket_api/main.py --port 8001. Créez un environnement Postman Local 8001 pour cette copie. Envoyez les requêtes aux deux copies en changeant uniquement d’environnement. Arrêtez ensuite la deuxième copie.

Quelle variable avez-vous modifiée, et quelles requêtes avez-vous modifiées?

Afficher la réponse

Une seule valeur : baseUrl = http://127.0.0.1:8001 dans le nouvel environnement. Aucune requête n’a changé. C’est le but des variables : les requêtes décrivent quoi envoyer, et l’environnement indique où.

Erreur courante

Une vraie clé d'API dans une valeur partagée

Symptôme : vous partagez la collection ou l’environnement avec un collègue, ou vous l’exportez. Le fichier ou son application Postman affiche votre vraie clé d’API.

Cause : la clé était dans la valeur partagée de la variable ou directement dans un en-tête de requête. Les valeurs partagées sont synchronisées avec le nuage de Postman et incluses lors du partage ou de l’exportation. La clé a quitté votre ordinateur.

Solution :

1. Considérez la clé comme divulguée : révoquez-la et créez-en une nouvelle, comme dans Configuration et secrets.
2. Placez la nouvelle clé uniquement dans la valeur locale de apiKey. Laissez la valeur partagée vide et marquez la variable comme sensible.
3. Utilisez {{apiKey}} dans Authorization de la collection, jamais la clé elle-même dans une requête.

Vérifiez votre compréhension

La collection contient baseUrl = http://127.0.0.1:8000, et l'environnement Postman actif contient baseUrl = http://127.0.0.1:8001. Où va une requête avec {{baseUrl}}?

Afficher la réponse

À http://127.0.0.1:8001. Une variable d’environnement remplace une variable de collection du même nom. Postman affiche la valeur de la collection barrée. Si vous ne choisissez aucun environnement, la requête utilise la valeur de la collection, soit le port 8000.

Vérifiez votre compréhension

Pourquoi apiKey a-t-elle une valeur partagée vide et une vraie valeur locale, plutôt que l'inverse?

Afficher la réponse

Les valeurs partagées sont synchronisées avec le nuage de Postman et incluses lors du partage ou de l’exportation de la collection ou de l’environnement. Les valeurs locales restent sur votre ordinateur. Un secret ne doit jamais quitter votre ordinateur, donc il va uniquement dans la valeur locale. La valeur partagée vide indique tout de même que la variable existe. Un collègue sait ainsi qu’il doit définir sa propre clé.

Récapitulatif

• {{name}} est une variable. Postman la remplace avant d’envoyer la requête.
• Un environnement Postman est un ensemble nommé de variables. Ses valeurs remplacent celles de la collection.
• Gardez l’URL dans baseUrl pour chaque environnement. Les mêmes requêtes fonctionnent ainsi localement et après le déploiement.
• Placez les secrets uniquement dans la valeur locale, avec une valeur partagée vide, et marquez la variable comme sensible.
• Définissez la clé d’API une seule fois, dans Authorization de la collection. Les requêtes en héritent.
• Les exemples enregistrés montrent les réponses exactes aux autres développeurs.

Ensuite, vous ajouterez des tests à chaque requête et exécuterez toute la collection depuis le terminal.

Leçon suivante : Tests et exécutions reproductibles