Variables et baseUrl dans Postman

1. Le copier-coller d'URL et ses conséquences

Tant qu'il n'y a qu'une ou deux requêtes, il semble logique de simplement insérer l'URL complète et de vivre heureux. Mais la collection Postman grandit très vite : différentes variantes de recherche, différentes requêtes de détails, vérifications de différents paramètres – et vous réalisez soudain que « insérer l'URL » devient un copier-coller sur des dizaines de lignes. Or, le copier-coller en ingénierie, c'est comme du sable dans les dents : tolérable les 30 premières secondes, puis on a envie de demander « mais pourquoi est-ce que je fais ça ? »

Imaginez que vous ayez 12 requêtes dans votre collection, et que chacune contienne en dur l'adresse du service. Le fournisseur change de domaine (ou vous décidez de tester via un proxy, ou on vous donne une adresse de staging) – et vous commencez à corriger manuellement la même chose 12 fois. En cours de route, vous allez forcément en oublier une, puis passer une demi-heure à chercher pourquoi « tout fonctionne sauf une ». Spoiler : parce qu'il en reste une avec l'ancien domaine.

Comparons « avant » et « après » l'introduction des variables :

# Avant (rigide et fragile) : adresse et paramètres figés dans la chaîne
https://catalog.example.com/search?q=clean+code&limit=3

# Après (modèle réutilisable) : adresse et valeurs séparés
{{baseUrl}}/search?q={{searchQuery}}&limit={{limit}}

Dans la première ligne, tout est figé : l'adresse et les paramètres. Dans la seconde, l'URL devient un modèle lisible : l'adresse du service séparée, la phrase de recherche séparée, la limite séparée. Et maintenant, « changer d'adresse » ne signifie plus réécrire 12 requêtes, mais modifier une seule valeur dans l'environnement.

2. Les environnements et l'environnement actif

Le mot « environnement » sonne comme si nous allions ouvrir un portail vers DevOps et commencer à parler de Kubernetes. Non, aujourd'hui c'est plus simple et plus agréable. Dans Postman, l'environnement est un ensemble de variables qui sont substituées dans les requêtes à la place de {{...}}. On peut le voir comme une boîte étiquetée : « pour ce service, l'adresse est celle-ci, la limite est celle-ci, la requête est celle-ci ».

L'idée clé est que la même requête peut être exécutée avec différents ensembles de valeurs. Pour cela, Postman introduit la notion d'environnement actif : vous le sélectionnez dans l'interface (généralement en haut à droite), et tous vos {{var}} se réfèrent alors aux valeurs de cet environnement. Si vous ne sélectionnez pas d'environnement, les variables ne seront pas substituées (ou le seront de manière inattendue), et vous obtiendrez l'erreur classique : « pourtant tout est correct, pourquoi ça ne marche pas ? »

Pour éviter toute confusion, il est utile de garder en tête une petite « cartographie » de qui fait quoi :

Un petit détail important : dans Postman, une variable a souvent deux valeurs – Initial et Current. Même si vous ne travaillez pas en équipe, il est utile de comprendre leur sens. Initial est la valeur « par défaut » (souvent celle qui apparaît dans l'export), tandis que Current est celle réellement utilisée localement à l'instant présent. Si un jour vous voyez qu'une variable « a l'air remplie » mais qu'elle se substitue vide, vérifiez d'abord si le remplissage est dans Initial ou Current.

3. baseUrl et l'adresse de base de l'API

baseUrl n'est ni un mot magique ni une fonction spéciale de Postman. C'est simplement une convention : nous extrayons le socle d'adresse commun du service dans une variable pour éviter de le répéter dans chaque requête. Et c'est l'une de ces petites habitudes qui font soudain de vous « la personne dont la collection ne s'effondre pas au bout d'une semaine ».

Que contient généralement baseUrl ? En général, c'est scheme + host (+ port), parfois aussi un préfixe de chemin de base si celui-ci est fixe pour l'API. Exemples :

# Variante 1 : l'API est à la racine du domaine (schéma + hôte seulement)
baseUrl = https://catalog.example.com

# Variante 2 : l'API est sous un préfixe (schéma + hôte + préfixe de chemin commun)
baseUrl = https://catalog.example.com/api

Que ne doit baseUrl pas contenir ? Elle ne doit pas contenir d'endpoints spécifiques (/search, /books/...) ni de paramètres de requête (?q=...). Si vous mettez /search?q=... dans baseUrl, vous ne créez pas une base – vous ne faites que déplacer la fragilité ailleurs.

Un sujet à part : « comment s'accorder sur les slashs », car c'est sur les slashs que la moitié des collections débutantes échoue. Il vaut mieux choisir une règle et s'y tenir, sinon vous finirez tôt ou tard par créer un monstre du genre https://catalog.example.com//search et vous vous demanderez : « est-ce seulement valide ? »

Dans ce cours, nous fixerons la règle suivante : baseUrl est stockée sans / final, et les chemins dans les requêtes commencent par /. Ainsi, la concaténation est toujours prévisible :

# Dans l'environnement : baseUrl sans slash final
baseUrl = https://catalog.example.com

# Dans la requête : le chemin commence par un slash
modèle = {{baseUrl}}/search

# Chaîne finale après substitution des variables
résultat = https://catalog.example.com/search

Cela semble ennuyeux, mais « ennuyeux » est une bonne chose. Ennuyeux signifie prévisible. Et prévisible signifie que ça ne casse pas au pire moment.

Un petit schéma pour fixer l'idée :

flowchart LR
    %% Postman substitue les valeurs de l'environnement actif dans le modèle de requête
    E["Environnement baseUrl, searchQuery, limit"] --> T["Modèle de requête {{baseUrl}}/search?..."]
    T --> S[Envoyer]
    S --> R["Requête réelle https://.../search?..."]

Postman fait une chose simple : il prend le modèle, substitue les valeurs de l'environnement actif, et envoie la requête HTTP « réelle ».

4. Quelles valeurs extraire dans des variables

À ce stade, il est facile de tomber dans deux extrêmes. Le premier extrême : n'extraire que baseUrl et continuer à modifier tout le reste à la main dans l'URL. Le second extrême : extraire absolument tout, y compris « la lettre préférée de l'auteur du cours » et « l'humeur de votre chat », puis ne plus comprendre d'où vient quoi.

L'approche saine est très pragmatique : extrayez dans des variables ce qui est souvent répété, souvent modifié, ou utilisé dans plusieurs requêtes. Dans notre scénario de catalogue, ce sont généralement searchQuery et limit. Un peu plus tard, une variable pour l'identifiant du livre apparaîtra, par exemple bookId (pour l'instant, on peut la définir manuellement, juste pour voir comment elle se substitue).

Voici le « kit du débutant » minimal qui rend déjà une collection pratique :

{
  // Adresse de base du service : change lors du basculement de plateforme/proxy
  "baseUrl": "https://catalog.example.com",

  // Phrase de recherche : pratique à modifier sans toucher à la requête elle-même
  "searchQuery": "clean code",

  // Dans Postman, les variables sont stockées sous forme de chaînes – c'est normal pour les paramètres de requête
  "limit": "3",

  // Identifiant du livre : utile pour les requêtes de détails
  "bookId": "BK-101"
}

Remarquez les guillemets autour de limit. Dans Postman, les valeurs des variables sont des chaînes. Même si logiquement vous pensez « la limite est un nombre », dans l'environnement elle est stockée comme "3". C'est normal. Le service destinataire recevra de toute façon le paramètre sous forme de chaîne et le convertira en nombre (s'il est conçu ainsi).

Autre point subtil mais important concernant les noms : il est préférable de nommer la variable d'après son sens plutôt que d'après « le nom du paramètre dans l'URL ». Le paramètre peut être q, mais la variable devrait plutôt s'appeler searchQuery, car dans une semaine vous aurez oublié ce qu'est q, alors que searchQuery ne s'oubliera que si vous souffrez d'amnésie (et encore, c'est pas sûr).

5. Modèles de variables et lisibilité

La syntaxe {{variableName}} dans Postman signifie simplement « substitue ici la valeur de la variable ». Il est important de noter que cela fonctionne non seulement dans l'URL, mais aussi dans d'autres parties de la requête : dans les paramètres de requête, les en-têtes et même dans le corps (si vous envoyez du JSON). Nous n'allons pas compliquer aujourd'hui, mais il est utile de savoir que les variables sont une substitution universelle.

La méthode la plus courante consiste à insérer les variables directement dans l'URL. C'est rapide et visuel :

# Modèle de requête : Postman substitue les valeurs des variables de l'environnement actif
{{baseUrl}}/search?q={{searchQuery}}&limit={{limit}}

Mais il existe une méthode encore plus propre, surtout pour les débutants : laisser l'URL « nue » et définir les paramètres de requête dans le tableau Params. Ainsi, Postman assemble lui-même correctement le ? et le &, et encode soigneusement les espaces et caractères spéciaux. L'idée est la suivante :

# URL sans paramètres de requête : il est préférable de définir les paramètres dans Params
URL : {{baseUrl}}/search

Et les paramètres se présentent comme un tableau :

Au final, vous obtenez une requête qui se lit presque comme une documentation : « on va sur /search, on transmet q et limit ». Et vous réduisez les risques d'erreur sur les ?, &, les espaces superflus et autres « symboles du destin » qui cassent la requête au moment où vous voulez juste apprendre tranquillement.

Pour une requête de détails d'un livre, le modèle est généralement encore plus simple et élégant :

# Détails du livre : la variable bookId est substituée dans le chemin
{{baseUrl}}/books/{{bookId}}

On voit très clairement ici pourquoi les variables sont utiles : l'endpoint se lit comme « détails du livre par id », et la valeur spécifique de bookId vit séparément. Et ce sera particulièrement agréable lorsque vous commencerez à basculer d'un environnement à l'autre : la requête ne change pas, seules les valeurs changent.

6. Discipline des noms et des formats

Dans Postman, il n'y a pas de « police architecturale » qui viendrait vous dire que vous avez mal nommé une variable. Par conséquent, la discipline apparaît non pas parce que « c'est la norme », mais parce que sinon vous vous infligez un jeu de piste de l'attention. C'est particulièrement vrai dans un projet pédagogique où la reproductibilité est importante : vous devez pouvoir ouvrir la collection demain et la comprendre sans avoir à fouiller.

Le problème le plus fréquent est le chaos dans les noms. Dans une requête c'est {{url}}, dans une autre {{host}}, dans une troisième {{apiUrl}}, et dans une quatrième carrément {{baseURL}} (avec une casse différente). Postman essaiera honnêtement de substituer, mais si la variable n'existe pas, il ne pourra tout simplement pas. Le résultat ressemble à « la requête est étrangement surlignée et le serveur ne répond pas ». Le secret, c'est que vous avez appelé une variable qui n'existe pas.

Le deuxième classique : des règles différentes concernant les slashs dans différents environnements. Par exemple, dans un environnement baseUrl = https://catalog.example.com/ (avec slash), et dans un autre baseUrl = https://catalog.example.com (sans slash). Si les requêtes sont écrites comme {{baseUrl}}/search, alors dans le premier environnement on obtiendra //search. Parfois le serveur « avale » le double slash, parfois non, parfois le proxy se comportera bizarrement. Mieux vaut ne pas tester la patience de votre serveur et uniformiser la règle.

Le troisième problème : essayer de mettre trop de choses dans baseUrl. On y met /search, parfois même ?limit=3. Ensuite, on essaie de faire une requête de détails et on se demande « comment est-ce qu'on concatène tout ça ? ». La réponse est simple : on ne concatène pas. baseUrl doit être une base, pas la moitié d'une requête spécifique.

Si vous voulez rendre votre collection lisible « comme un livre », une tradition pratique consiste à s'accorder sur un ensemble minimal de noms et à s'y tenir dans toutes les requêtes du catalogue : baseUrl, searchQuery, limit, bookId. Non pas parce que ce sont les seuls mots corrects, mais parce que des mots unifiés signifient moins de bruit inutile.

7. Basculer entre environnements et adresses

L'un des principaux avantages des environnements, vous ne le ressentirez pas immédiatement, mais quand viendra le besoin de « cette même requête, mais vers une autre source ». Cela peut être un autre domaine, une autre plateforme, un autre proxy, ou simplement une substitution temporaire du service. Et au lieu de réécrire l'URL dans chaque requête, vous basculez simplement l'environnement actif.

Il est très pratique de créer au moins deux environnements dès maintenant, même si le second est « pédagogique ». Par exemple :

Important : nous ne discutons pas encore de ce qui se cache derrière alt ni de la façon dont les réponses sont structurées. Ce qui nous importe ici, c'est le principe : les requêtes restent des modèles, et « où on tire » est déterminé par l'environnement.

Et c'est là qu'apparaît un petit rituel quotidien du développeur Postman : avant d'appuyer sur Envoyer, vous vérifiez une seconde quel environnement est actif. C'est un peu comme lorsque vous vérifiez dans un projet Java que vous lancez la bonne configuration (dev, test, prod), mais ici c'est plus simple : une seule liste déroulante.

Une autre habitude qui épargne les nerfs : utilisez la vue des variables d'environnement (dans Postman, c'est généralement l'icône en forme d'œil à côté de la sélection de l'environnement). Vous ouvrez la liste et voyez rapidement : à quoi est égal baseUrl, à quoi est égal searchQuery. Si c'est vide, alors « la requête n'est pas en cause », c'est l'environnement qui est en cause (ou le fait que vous ne l'avez pas sélectionné).

8. Erreurs typiques lors du travail avec les variables

Quand on commence à travailler avec des variables, les premiers problèmes sont presque toujours les mêmes, et c'est même une bonne chose : ils sont faciles à apprendre à reconnaître. Si vous connaissez ces pièges à l'avance, vous ne tomberez pas dedans jusqu'au cou, mais vous les enjamberez prudemment et continuerez, en gardant votre fierté et votre temps.

Erreur n°1 : l'adresse du service est codée en dur dans chaque requête.
Cela semble anodin tant qu'il y a peu de requêtes, mais cela se transforme rapidement en loterie : « où ai-je oublié de changer le domaine ? ». Le remède est simple : extrayez la partie commune dans baseUrl et écrivez toutes les requêtes via {{baseUrl}}/.... Ainsi, changer d'adresse revient à modifier une seule variable, et non à chasser le copier-coller.

Erreur n°2 : la même valeur est appelée par des noms différents (url, host, apiUrl).
Le problème n'est pas que les mots soient « mauvais », mais que le cerveau humain est limité : il n'est pas obligé de se souvenir que apiUrl et host signifient la même chose. Choisissez un seul nom (dans ce cours, ce sera baseUrl) et tenez-vous-y partout. Cela rend la collection lisible et réduit les risques de faire référence accidentellement à une variable inexistante.

Erreur n°3 : dans un environnement, baseUrl se termine par un slash, dans un autre non.
À cause de cela, les requêtes s'assemblent différemment : parfois un slash, parfois deux, parfois « collés sans slash ». Il est préférable de fixer une règle à l'avance (par exemple, baseUrl toujours sans / final) et de s'y tenir dans tous les environnements. Ainsi, les modèles d'URL fonctionneront de la même manière.

Erreur n°4 : on met trop de choses dans baseUrl : des paramètres de requête ou un endpoint spécifique.
Si baseUrl contient /search?q=..., vous ne construisez plus des requêtes, vous commencez à jongler avec des chaînes. Stockez dans baseUrl uniquement le socle d'adresse du service, et gardez le chemin et les paramètres dans la requête (idéalement via Params), sinon la collection devient fragile.

Erreur n°5 : on oublie de sélectionner l'environnement actif avant d'envoyer la requête.
C'est l'erreur la plus humaine : vous avez tout configuré, mais Postman envoie quand même « ailleurs » ou ne substitue pas les variables. Avant Envoyer, vérifiez une seconde quel environnement est actif, et si nécessaire ouvrez la vue rapide des variables. Cela prend deux secondes et vous épargne dix minutes d'agacement.