Utiliser Postman pour jouer avec les API
Maîtrisez les tests d'API avec Postman. Utilisez-le comme un véritable outil de tests unitaires pour valider le statut des réponses, imposer une structure de données et éviter les régressions dans votre workflow de développement d'API.
Traduction automatique
Cet article a plus d'un an, mais il a été relu le 30 juillet 2026 — son contenu est toujours exact.
Cet article fait partie de la série Construire et tester des API REST :
Cet article montre comment utiliser Postman comme outil de tests unitaires pour les API : mise en place des environnements et des collections avec des assertions partagées, puis écriture de contrôles pm.test() pour les codes de statut, le temps de réponse, les en-têtes content-type et — avec, comme fil rouge, un service SOAP de validation de numéro de TVA — des assertions poussées sur la structure XML/JSON : nœuds, collections et valeurs précises.
Si vous développez votre propre API (peu importe le langage — Python FastAPI prend environ une minute) ou si vous devez en consommer une, Postman peut se révéler très pratique.
Postman exige un compte et stocke vos collections dans son cloud. Pour une alternative 100 % locale et compatible avec Git, voyez Bruno - Un outil à la Postman - GUI et CLI.
Appeler une API et récupérer la réponse, c'est une chose, et c'est même assez simple. Mais une fonctionnalité sympa de Postman est la possibilité de valider la réponse : s'assurer que le type retourné est par exemple application/json, que le code de statut HTTP est 200, que le corps de la réponse est un objet JSON (ou une chaîne XML), que ce corps contient certaines informations obligatoires, et ainsi de suite.
Vous pouvez aussi valider la réponse par rapport à un schéma donné pour vérifier que la structure est bien celle attendue.
Dans cet article, nous allons utiliser Postman comme un outil de tests unitaires, c'est-à-dire lancer des contrôles sur notre propre API et faire un maximum d'assertions. Cela améliore la qualité de votre code en mettant en évidence les erreurs potentielles et, pour tout refactoring futur, relancer les tests vous garantira que vous n'avez rien cassé ; que vous n'avez aucune régression. Être sûr de ne pas avoir cassé une API quand vous mettez du code à jour, ça vaut de l'or.
Vous pouvez télécharger Postman gratuitement ici : https://www.postman.com/. Il faudra créer un compte avant de pouvoir télécharger le programme. La documentation se trouve sur https://learning.postman.com/docs/introduction/overview/ ; cet article n'expliquera donc pas en détail comment utiliser le programme mais donnera simplement quelques astuces.
Créer un environnement
Créer un environnement, c'est comme créer des variables globales.
Dans l'exemple ci-dessus, je définis mon base_url avec l'URL de mon web service.
Pensez bien à activer l'environnement (voir le point 2 sur l'image).
Dès à présent, je peux donc créer une requête et utiliser {{base_url}}
Créer une collection
Si vous devez créer plus d'une requête, mieux vaut créer une collection (comprenez un projet). Vous pourrez y stocker toutes vos requêtes, mais le plus gros avantage est de pouvoir définir des règles par défaut comme, par exemple, des tests à lancer pour chaque requête :
Ainsi, quelle que soit la requête que je lance, les quatre tests ci-dessous seront toujours exécutés :
pm.test("response is ok", function () {
pm.response.to.have.status(200);
});
pm.test("Content-Type header is present", () => {
pm.response.to.have.header("Content-Type");
});
pm.test("Content-Type header is text/xml", () => {
pm.expect(pm.response.headers.get('Content-Type')).to.include('text/xml; charset=utf-8');
});
pm.test("Don't contain any error", function ()
{
pm.expect(pm.response.text()).to.not.include("error");
});
Créer une requête
En créant une nouvelle requête, pour passer des informations dans l'en-tête, il me suffit de cliquer sur l'onglet Headers puis de renseigner la clé que je souhaite envoyer. Dans l'exemple d'une requête SOAP (c'est-à-dire appelée avec une enveloppe XML), je devrai envoyer une clé SOAPAction avec le nom de l'action à lancer (testFlag ici) et je préciserai que le corps envoyé est de type application/xml.
Ensuite, puisque cet exemple concerne une requête SOAP, je dois envoyer un corps XML, tel qu'attendu par l'action :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="{{wsdl}}">
<soapenv:Header />
<soapenv:Body>
<ns1:testFlagInput />
</soapenv:Body>
</soapenv:Envelope>
Le placeholder {{wsdl}} est une variable définie dans l'environnement.
Et, en option, nous pouvons aussi ajouter un test spécifique à la requête :
pm.test("status OK", function () {
var jsonObject = xml2Json(responseBody);
var status = jsonObject["SOAP-ENV:Envelope"]["SOAP-ENV:Body"]["ns1:testFlagOutput"]["status"];
return status == "OK"
});
Remplacez `testFlag` par le nom de votre nœud
En lançant la requête, dans cet exemple, nous exécuterons cinq tests puisque nous avons déjà défini quatre tests pour la collection.
Exporter / importer une collection
En regroupant toutes vos requêtes dans une collection, vous pouvez facilement l'exporter (sous forme de fichier .json)
Et, bien sûr, l'importer presque de la même manière :
Exemple concret
Comme vu dans l'article MS Excel - Comment appeler un web service SOAP, nous pouvons appeler un web service européen pour vérifier la validité d'un numéro de TVA.
Essayons avec Postman :
L'URL de base du service est http://ec.europa.eu/taxation_customs/vies/services/checkVatService, la méthode doit être POST et nous devons définir l'en-tête SOAPAction à checkVAT.
Ensuite, nous devons envoyer un corps XML spécifique. Pour l'exemple, nous allons interroger un numéro de TVA en Belgique.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<urn:checkVat xmlns:urn="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
<urn:countryCode>BE</urn:countryCode>
<urn:vatNumber>0403170701</urn:vatNumber>
</urn:checkVat>
</soapenv:Body>
</soapenv:Envelope>
En lançant la requête, Postman renvoie :
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<ns1:checkVatResponse xmlns:ns1="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
<ns1:countryCode>BE</ns1:countryCode>
<ns1:vatNumber>0403170701</ns1:vatNumber>
<ns1:requestDate>2024-03-05+01:00</ns1:requestDate>
<ns1:valid>true</ns1:valid>
<ns1:name>SA ELECTRABEL</ns1:name>
<ns1:address>Boulevard Simon Bolivar 36 1000 Bruxelles</ns1:address>
</ns1:checkVatResponse>
</env:Body>
</env:Envelope>
Quelques contrôles
J'utilise `{{wsdl}}` comme placeholder
Dans les exemples ci-dessous, vous verrez {{wsdl}} dans les extraits de code XML. Ce n'est qu'un placeholder : en situation normale, vous y retrouverez une URL vers un service WSDL (ou une API REST).
Contrôler des métriques comme le responseTime
Si vous souhaitez valider le temps de réponse d'une requête, par exemple 500 ms :
pm.test('Response time is within an acceptable range', function () {
pm.expect(pm.response.responseTime).to.be.below(500);
})
Contrôler le code de statut HTTP
Valider que le code de statut de la réponse est 200 :
pm.test('Response status code is 200', function () {
pm.expect(pm.response.code).to.equal(200);
})
S'assurer que la réponse renvoie un content-type
pm.test("Content-Type header is present", () => {
pm.response.to.have.header("Content-Type");
});
Et si nous voulons vérifier la valeur du content-type retourné :
pm.test("Content-Type header is text/xml", () => {
pm.expect(pm.response.headers.get('Content-Type')).to.include('text/xml; charset=utf-8');
});
Vérifier que la réponse est une chaîne XML valide
Test simple pour s'assurer que nous avons bien reçu une réponse XML valide :
pm.test('Response body is in valid XML format', function () {
const responseData = pm.response.text();
try {
xml2Json(responseData);
pm.expect(true).to.be.true;
} catch (error) {
pm.expect.fail('Response body is not in valid XML format');
}
})
Valider l'absence ou la présence de certains mots
Analyser la réponse comme une chaîne et s'assurer que le mot error n'est pas présent :
pm.test("Don't contain any error", function ()
{
pm.expect(pm.response.text()).to.not.include("error");
});
Cet exemple échouera donc dès que le mot error apparaît dans la réponse retournée.
Ou, à l'inverse, s'assurer que certains mots sont bien présents dans la réponse :
pm.test("Assert 'is successful'", function ()
{
pm.expect(pm.response.text()).to.include("is successful");
});
Faire des assertions sur l'absence de nœuds
Cette assertion est plus spécifique. Elle échouera dès qu'un nœud <error> est présent dans la réponse.
pm.test("The error node shouldn't be part of the response", function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:testOutput']['error']).to.not.exist;
})
Si votre réponse est celle ci-dessous, l'assertion échouera puisque <ns1:testOutput> contient un nœud <error>.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="{{wsdl}}">
<SOAP-ENV:Body>
<ns1:testOutput>
<error>
<!-- ... -->
</error>
</ns1:...>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Faire des assertions sur la présence de nœuds
À titre d'exemple, nous allons nous assurer que la réponse contient toujours <SOAP-ENV:Envelope> et <SOAP-ENV:Body> :
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="{{wsdl}}">
<SOAP-ENV:Body>
<!-- ... -->
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
pm.test('Validate SOAP-ENV:Envelope and SOAP-ENV:Body elements are present', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData).to.have.property('SOAP-ENV:Envelope');
pm.expect(responseData['SOAP-ENV:Envelope']).to.exist;
pm.expect(responseData['SOAP-ENV:Envelope']).to.have.property('SOAP-ENV:Body');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']).to.exist;
})
`to.exist` est équivalent à `to.have.property`
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']).to.exist peut aussi s'écrire comme ceci : pm.expect(responseData['SOAP-ENV:Envelope']).to.have.property('SOAP-ENV:Body');
Pour du XML, vérifier la valeur d'un nœud donné
Si vous souhaitez vous assurer qu'un nœud donné possède une propriété spécifique :
pm.test('Response body has the required fields', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.have.property('SOAP-ENV:Envelope');
pm.expect(responseData['SOAP-ENV:Envelope']).to.have.property('SOAP-ENV:Body');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']).to.have.property('ns1:testFlag');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:testFlag']).to.have.property('count');
pm.expect(responseData['SOAP-ENV:Body']['ns1:getSessionsLanguagesOutput'].list).to.exist;
})
Assertions sur les collections
Imaginons que votre réponse retourne une collection comme, ci-dessous, une liste de langues :
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="{{wsdl}}">
<SOAP-ENV:Body>
<ns1:getLanguagesOutput>
<list>
<description>English</description>
<iso>en</iso>
<language>E</language>
</list>
<list>
<description>Français</description>
<iso>fr</iso>
<language>F</language>
</list>
<list>
<description>Nederlands</description>
<iso>nl</iso>
<language>N</language>
</list>
</ns1:getLanguagesOutput>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Assurez-vous que le nœud list existe :
pm.test('List array contains at least one element', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput']).to.have.property('list');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput']['list']).to.exist;
})
Vous voulez vous assurer qu'il y a au moins un enregistrement :
pm.test('List array contains at least one element', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput'].list).to.be.an('array').and.to.have.lengthOf.at.least(1);
})
Vérifier que chaque élément de la liste contient bien les nœuds attendus ; par exemple :
pm.test('Validate expected structure', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput']).to.have.property('list');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput'].list).to.be.an('array').and.to.have.lengthOf.at.least(1);
responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput']['list'].forEach(function (node) {
pm.expect(node.description).to.exist.and.to.not.be.empty;
pm.expect(node.iso).to.exist.and.to.not.be.empty;
pm.expect(node.language).to.exist.and.to.not.be.empty;
});
})
Quand le <list></list> ne contient qu'un seul élément (et donc pas un tableau) :
pm.test('Validate expected structure', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput']).to.have.property('list');
const list = responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getLanguagesOutput']['list']
pm.expect(list).to.have.property('description').and.to.not.be.empty;;
pm.expect(list).to.have.property('iso').and.to.not.be.empty;;
pm.expect(list).to.have.property('language').and.to.not.be.empty;;
})
Assertions sur les valeurs
Vérifier la valeur
Imaginez que vous ayez quelque chose comme ceci et que vous vouliez vérifier que le statut est OK :
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="{{wsdl}}">
<SOAP-ENV:Body>
<ns1:testFlagOutput>
<status>OK</status>
</ns1:testFlagOutput>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
pm.test("status OK", function () {
var jsonObject = xml2Json(responseBody);
var status = jsonObject["SOAP-ENV:Envelope"]["SOAP-ENV:Body"]["ns1:testFlagOutput"]["status"];
return status == "OK"
});
Même idée, mais nous allons nous assurer que la propriété count est correctement définie, c'est-à-dire avec un nombre.
pm.test("Returned count is a number", function () {
var jsonObject = xml2Json(responseBody);
var count = jsonObject["SOAP-ENV:Envelope"]["SOAP-ENV:Body"]["ns1:testFlagOutput"]["count"];
pm.expect(Number.isInteger(count));
});
Si vous avez un nœud error dans votre réponse, assurez-vous que la propriété du code d'erreur n'est pas vide :
pm.test('Error code is not empty', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:testFlag'].error.code).to.exist.and.to.not.be.empty;
})
Et si vous avez aussi une propriété contenant le message d'erreur, vérifiez qu'elle n'est pas vide mais contient bien une description de l'erreur.
pm.test('Error message is not empty', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:testFlag']['error']['message']).to.exist.and.to.not.be.empty;
})
Contrôles sur une valeur de type date
Vous avez une liste d'employés dans une collection et vous souhaitez vérifier le birthDate :
pm.test('Validate birthDate is null or in a valid date format', function () {
const responseData = xml2Json(pm.response.text());
pm.expect(responseData).to.be.an('object');
pm.expect(responseData['SOAP-ENV:Envelope']['SOAP-ENV:Body']['ns1:getEmployeesOutput']['list']['birthDate']).to.satisfy(function (date) {
return date === null || new Date(date).toString() !== 'Invalid Date';
});
})
Cet article fait partie de la série Construire et tester des API REST :
Articles liés
Bruno - Un outil à la Postman - GUI et CLI
7 août 2025
API REST - Comment écrire de bonnes API
19 mai 2025
