Informatique · Web et réseaux

Tester une API avec Postman

Avant d'écrire une ligne d'appli, tu veux savoir si l'API répond, avec quels codes et quelles données. Postman sert à ça.

Déjà à l'aise ? Aller au quiz

Le point de départ

Une appli de classe affiche des articles venus d'une API. Avant de coder, tu envoies une requête à la main et tu lis la réponse.

GET {{base_url}}/posts/1 Send 200 OK { "userId": 1, "id": 1, "title": "sunt aut…" } Tests : 2 / 2 statut 200 userId = 1

Tout se vérifie à la main, avant la moindre ligne d'appli.

Après cette fiche, tu sais

  • envoyer une requête dans Postman et lire la réponse : code, en-têtes, corps ;
  • organiser des requêtes en collection et changer d'environnement grâce aux variables ;
  • écrire des tests automatiques avec pm.test et enchaîner des requêtes ;
  • lancer toute une collection avec le Collection Runner, la Postman CLI ou Newman ;
  • reconnaître ce qu'un test prouve, et ce qu'il ne prouve pas.
Je te pose une question à garder en tête : si une collection de tests passe au vert, est-ce la preuve que l'API marche ?

Oui, non ? Tu me diras si je me trompe.

On y répond dans la notion 4. Indice : le vert ne prouve que ce que les tests vérifient.

Premier envoi, premier code

Notion 1 · L'outil

Une requête, une réponse

Postman est un client HTTP graphique. Tu choisis la méthode, tu écris l'adresse, puis tu cliques sur Send. Il existe en application de bureau et en version web.

Postman ton ordinateur API le serveur GET /users 200 OK

Pour s'entraîner sans rien casser, on utilise une API de test.

Pour s'entraîner

JSONPlaceholder est une fausse API publique. Elle sert des articles, des utilisateurs et des commentaires. Ses lectures renvoient des données de test, et ses écritures sont simulées : rien n'est vraiment enregistré.1

Lire GET /users 10 utilisateurs de test renvoyés par l'API Écrire POST PUT PATCH DELETE simulé rien n'est enregistré

Un POST, un PUT, un PATCH ou un DELETE ne change rien de réel ici.

Ce que tu remplis

Une requête tient en quatre champs : la méthode, l'adresse, les en-têtes et le corps. Tu les remplis, puis tu envoies.

Méthode GET Adresse {{base_url}}/users En-tête Accept: application/json Corps vide pour un GET Send réponse [ { "id": 1, … } ] 200 OK

Pour un GET, le corps reste vide.

Ta première requête, en trois gestes

1. Nouvelle requête

Dans Postman, choisis New, puis HTTP.

2. Méthode et adresse

Choisis GET, puis tape https://jsonplaceholder.typicode.com/users.

3. Send

La réponse 200 OK contient la liste des 10 utilisateurs, en JSON.

Huit requêtes, huit vraies réponses

Fais défiler : chaque requête part vers JSONPlaceholder. Les codes affichés sont ceux que l'API a réellement renvoyés, y compris ses bizarreries.

Scène 1 · Dans Postman

Lire une liste

GET {{base_url}}/users Send ParamsAuthorizationHeadersBodyScripts Réponse 200 OK

Ce que tu reçois

La réponse a trois parties : une ligne d'état, des en-têtes, puis un corps. Postman affiche aussi le temps de réponse.

ligne d'état HTTP/1.1 200 OK en-têtes Content-Type: application/json corps [ { "id": 1, "name": "…" }, …

Le corps, ici du JSON13, est ce que ton programme lira.

10utilisateurs dans la réponse 200 OK de GET /users.1

Lire le code d'état

Le premier chiffre donne la famille : 2xx pour un succès, 3xx pour une redirection, 4xx quand le client s'est trompé, 5xx quand le serveur échoue.9

2xx réussi 200 OK · 201 Created · 204 No Content 3xx redirection une action de plus est nécessaire 4xx erreur du client 404 Not Found · 405 Method Not Allowed 5xx erreur du serveur 500 Internal Server Error

Un 404 dit seulement que la ressource demandée n'existe pas à cette adresse.9

Je m'arrête sur le 404 : c'est la faute de ta requête, ou celle de l'API ?

Tu veux dire que mon adresse est peut-être fausse ?

Commence par là : le 404 dit que rien ne se trouve à cette adresse. Vérifie l'URL avant d'accuser l'API.
Tu as vu ? L'article 101 n'est jamais vraiment créé, et un PUT sur l'article 999 répond 500 au lieu de 404. Une API d'entraînement a ses bizarreries : on teste sa vraie API avant de conclure.
VerbeDans PostmanChez JSONPlaceholder
GETpas de corps200, ou 404 si l'article n'existe pas
POSTBody → raw → JSON201 et un id 101, simulé
PUTcorps complet200 (500 pour un article inexistant)
PATCHseulement les champs à changer200, le reste de l'article intact
DELETEpas de corps200 et {} (beaucoup d'API répondent 204)

Le sens de chaque méthode et de chaque code est détaillé dans la fiche HTTP et REST. Quand tu choisis Body → raw → JSON, Postman ajoute l'en-tête Content-Type: application/json pour toi.

Sûre ou idempotente ?

Une méthode sûre ne modifie rien sur le serveur. Une méthode idempotente produit le même effet, qu'on l'envoie une ou plusieurs fois.9

méthode sûre idempotente GET oui oui PUT non oui DELETE non oui POST non non PATCH non non

PATCH n'est ni sûre ni idempotente.10 Une réponse peut changer (204 puis 404), mais l'état final reste le même.

Ranger, partager, lancer d'un coup

Notion 2 · Les collections

Ranger ses requêtes

Une collection regroupe les requêtes d'une même API, parfois en dossiers. On la sauvegarde, on la partage, on l'exporte en JSON, et on la lance d'un coup.

Blog API Tests collection Articles dossier GET tous les articles GET un article POST créer PATCH modifier le titre DELETE supprimer

Le Runner, vu à la notion 4, lance toutes ces requêtes d'un coup.

Les onglets d'une requête

Params

La partie ?clé=valeur de l'adresse.

Authorization

Le jeton, la clé d'API ou les identifiants.

Headers

Les en-têtes, comme Content-Type.

Body

Le corps envoyé, par exemple du JSON pour un POST.

Scripts

Le code exécuté avant l'envoi ou après la réponse.

Démonter une adresse

Une adresse se découpe : le protocole, le serveur, le chemin, puis les paramètres après le ?.12

https:// le protocole jsonplaceholder.typicode.com le serveur /posts la ressource ?userId=1 les paramètres

L'onglet Params écrit cette dernière partie à ta place.

Authorization : le jeton

Certaines API demandent un jeton. Avec le type Bearer Token, Postman ajoute pour toi l'en-tête Authorization: Bearer … à chaque envoi.14

GET /posts HTTP/1.1 Host: api.example.com Authorization: Bearer <ton-jeton> Le jeton voyage dans l'en-tête, jamais dans l'adresse. Jeton absent ou faux : 401. Droits insuffisants : 403.

Jeton absent ou faux : 401. Jeton valide, droits insuffisants : 403.9

Jamais de jeton dans l'adresse.11

Changer de serveur sans rien réécrire

Notion 3 · Variables et environnements

Une adresse, trois serveurs

Une même API tourne sur ta machine, sur un serveur de test, puis en production. Au lieu de corriger l'adresse partout, tu écris une variable, {{base_url}}, et chaque environnement lui donne sa valeur.

GET {{base_url}} /posts base_url = http://localhost:3000 Développement GET http://localhost:3000/posts

Postman remplace la variable au moment de l'envoi.

Un seul mot change, tout suit

Fais défiler : la même requête part vers trois serveurs, sans rien réécrire.

GET {{base_url}}/posts ADRESSE RÉELLEMENT APPELÉE (choisis un environnement)
Étape 1 sur 4

La requête contient {{base_url}} : Postman la remplacera par une valeur au moment de l'envoi.

Étape 2 sur 4 · développement

Environnement « Développement » : l'API tourne sur ta machine, port 3000.

Étape 3 sur 4 · test

Un clic sur « Test » : les mêmes requêtes visent le serveur de test, sans rien réécrire.

Étape 4 sur 4 · production

« Production » : la vraie API. Prudence avec les requêtes qui modifient ou suppriment.

Cinq portées

Une variable peut vivre à cinq niveaux : globale, de collection, d'environnement, de fichier de données, locale. Si le même nom existe à plusieurs niveaux, le plus étroit gagne.4

globale collection environnement fichier de données locale le plus étroit gagne

Une variable d'environnement l'emporte donc sur une variable de collection.

Un coffre pour les secrets

Pour un mot de passe ou un jeton, Postman propose un coffre (Postman Vault) plutôt qu'une variable partagée.4

variable partagée token = jeton-test visible par qui reçoit la collection ou l'export coffre token = •••••• valeur masquée, rangée à part

Une variable partagée peut se retrouver dans un fichier exporté.

Variables dynamiques

Postman fournit des variables recalculées à chaque envoi : {{$randomInt}} (un entier de 0 à 1 000), {{$randomEmail}}, {{$guid}} et {{$timestamp}} (l'heure Unix, en secondes).5

{{$randomInt}} entier de 0 à 1 000 {{$randomEmail}} adresse e-mail aléatoire {{$guid}} identifiant unique {{$timestamp}} heure Unix, en secondes une nouvelle valeur à chaque envoi

Dans un corps JSON : { "id": {{$randomInt}} }

Tester, c'est attendre quelque chose

Notion 4 · Les tests automatiques

Écrire ce qu'on attend

L'onglet Scripts a deux parties : Pre-request, exécuté avant l'envoi, et Post-response, exécuté après la réponse. Les scripts de la collection passent d'abord, puis ceux du dossier, puis ceux de la requête.2

Pre-request avant l'envoi pour préparer Envoi la requête part vers l'API Post-response après la réponse pour vérifier pm.test(…)

Les tests vivent dans Post-response.

Anatomie d'un test

Un test a un nom, une fonction et une assertion. On l'écrit en JavaScript, avec l'objet pm.8

pm.test("Le statut est 200", function () { pm.response.to.have.status(200); }); nom ce que le test prouve, en clair fonction le code qui vérifie assertion vérifie le code d'état

Si l'assertion est fausse, le test échoue.

Scripts → Post-responsejs
pm.test("Le statut est 200", function () {
  pm.response.to.have.status(200);
});
pm.test("La réponse est du JSON", function () {
  pm.response.to.be.json;
});
pm.test("L'article appartient à l'utilisateur 1", function () {
  const article = pm.response.json();
  pm.expect(article.userId).to.eql(1);
});
pm.test("Réponse en moins de 500 ms", function () {
  pm.expect(pm.response.responseTime).to.be.below(500);
});

Enchaîner deux requêtes

Un script post-réponse range une valeur dans une variable, que la requête suivante utilise.

POST /posts → Post-response, puis GET {{base_url}}/posts/{{postId}}js
const id = pm.response.json().id;   // 101 chez JSONPlaceholder
pm.environment.set("postId", id);
POST /posts → id 101 post-réponse pm.environment.set("postId", id); requête suivante GET {{base_url}}/posts/{{postId}}

Ici, l'id 101 vient de la réponse du POST.

Le Collection Runner

Le Runner lance toute une collection, une requête après l'autre, avec ses tests. On peut répéter le passage (itérations), attendre entre deux requêtes et fournir un fichier de données CSV ou JSON pour tester plusieurs cas.3

9tests, réparties sur six requêtes dans la collection du Runner.
Scène 2 · Collection Runner

Premier passage

Blog API Tests · JSONPlaceholder 0 test lancé

Réponse à ma question du début : non. Le vert prouve seulement que l'API a répondu ce que tes tests attendaient. Un test mal écrit, comme le 204 du DELETE, échoue sur une API correcte, et une fausse API peut tout réussir.
Exercice · à toi

Le bon script

Trois situations de tests. Choisis la bonne réponse : les scripts ont été exécutés avec Newman contre JSONPlaceholder.

Exercice · à toi

Avant ou après l'envoi ?

Range chaque tâche dans le script où elle doit s'écrire.

Place à l'intégration continue

Notion 5 · Automatiser

Les tests sans ouvrir Postman

Une collection exportée se lance en ligne de commande. Dans un pipeline d'intégration continue (GitHub Actions, GitLab CI…), elle est rejouée à chaque modification du code.

collection.json environnement.json postman collection run tests verts : tout passe un test rouge : arrêt

Une seule commande suffit, sans fenêtre Postman.

Postman CLI

L'outil en ligne de commande officiel de Postman, signé par l'éditeur.6 Une collection exportée en fichier se lance sans compte ; la connexion (postman login) sert notamment à publier les résultats dans Postman.

Newman

L'ancien lanceur, libre et toujours disponible. Il ne lit pas le nouveau format de collection v3 de Postman v12 et suivants : Postman conseille de passer à la Postman CLI.7

terminalbash
# Postman CLI
npm install -g postman-cli
postman collection run collection.json -e environnement.json

# Newman (collections au format v2.1)
npm install -g newman newman-reporter-html
newman run collection.json -e environnement.json -r cli,html
newman run collection.json --bail   # s'arrête au premier échec

Le rapport HTML de Newman demande le paquet newman-reporter-html, installé au même endroit que Newman : sans lui, -r html s'arrête avec « could not find "html" reporter ». Toutes ces commandes ont été testées (Postman CLI 1.67, Newman 6.2.2).

Un pipeline, à chaque envoi de code

Fais défiler : ce que fait un pipeline quand quelqu'un pousse du code.

déploiement arrêt, rien n'est publié
Étape 1 sur 4

Quelqu'un pousse une modification du code de l'API sur le dépôt.

Étape 2 sur 4

Le pipeline démarre : il installe l'API sur un serveur de test.

Étape 3 sur 4

Il lance la collection avec la Postman CLI : toutes les requêtes et tous les tests.

Étape 4 sur 4

Tests verts : l'API est déployée. Un seul test rouge : le pipeline s'arrête et prévient l'équipe.

Six pièges à éviter

Les pièges classiques

Une collection verte ne prouve pas tout

Elle prouve seulement ce que les tests vérifient. Contre JSONPlaceholder, les créations et suppressions sont simulées : rien n'est enregistré.

Le code « habituel » au lieu du code documenté

Beaucoup d'API répondent 204 à un DELETE, JSONPlaceholder répond 200. Un test se règle sur la documentation de l'API testée.

Un jeton en clair dans une collection partagée

Toute personne qui reçoit la collection récupère le jeton. Range les secrets dans le coffre de Postman, et jamais dans l'adresse : elle finit dans les journaux des serveurs.11

Le corps sans Content-Type

Un JSON envoyé comme texte brut peut être refusé ou mal lu. Choisis Body → raw → JSON, qui ajoute l'en-tête.

Croire qu'un test raté arrête tout

Le Runner continue avec les requêtes suivantes. Par défaut, il ne s'arrête que sur une erreur dans un script ou un échec d'envoi (option Stop run if an error occurs).3 Pour s'arrêter au premier test raté, Newman a l'option --bail.

Lancer des DELETE sur la production

Vérifie l'environnement choisi avant Send : la même requête vise un autre serveur selon l'environnement.

Entraîne-toi

Exercices corrigés

Cherche d'abord, puis ouvre le corrigé. Les scripts ont été exécutés avec Newman contre JSONPlaceholder.

1Écris un test qui vérifie que GET /posts renvoie exactement 100 articles.Voir le corrigé
pm.test("100 articles", function () {
  pm.expect(pm.response.json().length).to.eql(100);
});
2base_url existe dans la collection et dans l'environnement actif, avec deux valeurs différentes. Laquelle Postman utilise-t-il ?Voir le corrigé

Celle de l'environnement : de globale à locale, la portée la plus étroite gagne, et l'environnement est plus étroit que la collection.

3Un POST sur JSONPlaceholder renvoie 201 avec l'id 101. Juste après, GET /posts/101 renvoie 404. Bug ?Voir le corrigé

Non : JSONPlaceholder simule les écritures, l'article n'a jamais été enregistré. Contre une vraie API, ce même enchaînement serait un excellent test.

4Quelle commande lance la collection collection.json avec l'environnement test.json dans un pipeline, avec l'outil officiel de Postman ?Voir le corrigé
npm install -g postman-cli
postman collection run collection.json -e test.json

La mission, pour de vrai

Dans le vrai Postman

Mission : la collection Blog API

Ouvre Postman et refais la scène du Runner toi-même, contre JSONPlaceholder.

1 2 3 4 5 environnement · collection · tests · Runner · export 9 tests, tous verts dans le Runner, sur la collection Blog API
  1. Crée un environnement « JSONPlaceholder » avec la variable base_url = https://jsonplaceholder.typicode.com, puis sélectionne-le.
  2. Crée la collection « Blog API Tests » et ses six requêtes : GET /posts, POST /posts, GET /posts/{{postId}}, PUT /posts/1, PATCH /posts/1, DELETE /posts/1, toutes avec {{base_url}}.
  3. Ajoute les tests : 200, JSON et 100 articles pour GET /posts ; 201 et un id pour le POST, qui range aussi l'id dans postId ; 404 pour la relecture ; 200 pour les trois dernières.
  4. Lance la collection avec le Runner : neuf tests, tous verts.
  5. Exporte la collection et l'environnement en JSON, puis relance-les avec postman collection run.
Pour aller plus loinFais attendre 204 au test du PUT et relance : un test rouge, et le Runner lance quand même le PATCH et le DELETE. Remets 200 ensuite.

À retenir

La fiche en huit lignes

Postmanun client HTTP graphique : méthode, adresse, en-têtes, corps, puis la réponse complète.
JSONPlaceholderune fausse API d'entraînement : lectures réelles, écritures simulées.
Collectionles requêtes d'une API, rangées, partagées, exportées en JSON.
Variables{{base_url}} ; un environnement par serveur ; la portée la plus étroite gagne.
ScriptsPre-request avant l'envoi, Post-response après la réponse ; pm.test et pm.expect.
Enchaînerpm.environment.set("postId", …) puis {{postId}} dans la requête suivante.
Runnertoute la collection d'un coup ; un test raté n'arrête pas la suite.
En ligne de commandePostman CLI (officielle) ou Newman (collections v2.1) dans un pipeline.

Douze questions pour finir

Dernière étape, le quiz. Plusieurs questions portent sur les bizarreries de JSONPlaceholder : ce sont elles qui piègent le plus en vrai.
Quiz final

Teste-toi

Sources

  1. JSONPlaceholder, Guide (« The resource is not really created on the server, but the response is faked as if », de même pour les modifications et suppressions). jsonplaceholder.typicode.com, consulté le 8 octobre 2026.
  2. Postman, Use scripts to add logic and tests to Postman requests (onglet Scripts, Pre-request et Post-response, ordre collection, dossier, requête). learning.postman.com, consulté le 8 octobre 2026.
  3. Postman, Test your API using the Collection Runner (itérations, délai, fichiers de données, option Stop run if an error occurs, intégration continue avec la Postman CLI). learning.postman.com, consulté le 8 octobre 2026.
  4. Postman, Store and reuse values using variables (portées globale, collection, environnement, données, locale ; la plus étroite l'emporte ; Postman Vault). learning.postman.com, consulté le 8 octobre 2026.
  5. Postman, Use dynamic variables to return randomly generated data ($randomInt de 0 à 1000, $timestamp en secondes, $randomEmail, $guid). learning.postman.com, consulté le 8 octobre 2026.
  6. Postman, Postman CLI overview (« Postman's official, signed command-line tool ») et Install the Postman CLI (npm install -g postman-cli). présentation · installation, consulté le 8 octobre 2026.
  7. Postman, Run and test collections from the command line using Newman CLI (« Newman isn't compatible with the collection v3 format used in Postman v12 and later »). learning.postman.com, consulté le 8 octobre 2026.
  8. Postman, Write scripts to test API response data in Postman (onglet Scripts > Post-response, exemple pm.response.to.have.status(200)). learning.postman.com, consulté le 8 octobre 2026.
  9. Fielding R., Nottingham M., Reschke J., HTTP Semantics, RFC 9110, juin 2022 : méthodes sûres et idempotentes (§ 9.2), codes d'état (§ 15). rfc-editor.org, consulté le 8 octobre 2026.
  10. Dusseault L., Snell J., PATCH Method for HTTP, RFC 5789, mars 2010 : PATCH n'est ni sûre ni idempotente. rfc-editor.org, consulté le 8 octobre 2026.
  11. Jones M., Hardt D., The OAuth 2.0 Authorization Framework: Bearer Token Usage, RFC 6750, octobre 2012 : en-tête Authorization: Bearer, risques d'un jeton placé dans l'adresse. rfc-editor.org, consulté le 8 octobre 2026.
  12. Berners-Lee T., Fielding R., Masinter L., Uniform Resource Identifier (URI): Generic Syntax, RFC 3986, janvier 2005 : schéma, autorité, chemin et requête. rfc-editor.org, consulté le 8 octobre 2026.
  13. Bray T., éd., The JavaScript Object Notation (JSON) Data Interchange Format, RFC 8259, décembre 2017. rfc-editor.org, consulté le 8 octobre 2026.
  14. Postman, Authorization types supported by Postman (type Bearer Token, jeton ajouté à l'en-tête de la requête). learning.postman.com, consulté le 8 octobre 2026.

Fiche relue et sourcée en septembre 2026, refaite en récit en octobre 2026. Codes de JSONPlaceholder relevés le 1er octobre 2026 ; scripts exécutés avec Newman 6.2.2 et la Postman CLI 1.67.0.

Glisser pour continuer vers Réseaux