Premières requêtes dans Postman

Ce que vous saurez faire

Travaillez avec une API comme beaucoup d’équipes le font chaque jour : dans Postman. Chaque requête y est enregistrée, facile à modifier et à renvoyer. Vous partez du document OpenAPI de votre API. Tous les points de terminaison sont donc prêts en une étape.

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

Ce que vous devez savoir

• Votre tableau de contrat et ses lignes d’échec, tirés de Conception des ressources et des points de terminaison : règle 4 : écrire le contrat sous forme de tableau et de Validation et réponses d’erreur : exemple détaillé : une structure pour toutes les erreurs.
• D’où viennent le titre, les étiquettes et les résumés dans /openapi.json, selon Une documentation utilisable : d’où vient chaque partie de la documentation.

Ce qu’il vous faut sur votre ordinateur

• L’API fonctionne localement avec fastapi dev, et http://127.0.0.1:8000/openapi.json s’ouvre, comme à la fin de Garder la documentation exacte : exercice guidé : protéger le contrat. Si vous l’avez démarrée avec SHOW_DOCS=false, redémarrez-la sans cette variable.
• Si vous avez ajouté explanation dans l’exercice « À vous de jouer » de cette leçon, retirez-le. Exportez ensuite le contrat de nouveau, comme l’indique l’exercice.
• Un compte Postman gratuit. L’application Postman en exige un pour conserver les collections et les environnements. Le forfait Free (gratuit) s’adresse à une personne et ne nécessite aucun paiement. Si vous ne voulez pas de compte, vous pouvez suivre ce module avec Swagger UI et curl. L’interface en ligne de commande de Postman, dans la leçon 3, fonctionne sans compte.
• Environ 500 Mo d’espace disque pour l’application.
• Si votre projet manque ou ne fonctionne plus, copiez l’instantané end-of-m04, qui contient le projet à la fin du module 4. Utiliser un instantané présente les étapes.

Les étapes pour l’application suivent la documentation de Postman 12. L’équipe Postman modifie souvent l’application. Le nom ou l’emplacement d’un bouton peut donc varier légèrement.

Pourquoi un autre outil?

Vous pouvez déjà envoyer des requêtes avec curl et Swagger UI. Chacun a ses limites :

Outil	Utile pour	Peu adapté à
curl	Une requête, un script, un rapport de bogue	Beaucoup de requêtes, des corps longs, la comparaison des réponses
Swagger UI	Essayer les points de terminaison d’une API à partir de sa documentation	L’enregistrement des requêtes, plusieurs environnements, les tests
Postman	Conserver toutes vos requêtes, avec des noms, des variables et des tests, pour plusieurs API et environnements	Les tests automatisés dans le code (c’est le rôle de pytest)

Postman est un client API : une application pour créer, envoyer, enregistrer et tester des requêtes. Les requêtes sont conservées dans des collections. Ce sont des groupes nommés de requêtes, organisés en dossiers, que vous pouvez partager, exécuter et exporter. Beaucoup d’entreprises fournissent à leurs partenaires une collection Postman avec leur API, en plus du document OpenAPI.

Installer l’application et se connecter

1. Allez à postman.com/downloads et téléchargez l’application de bureau pour votre système.
2. Installez-la et ouvrez-la.
3. Connectez-vous avec votre compte Postman ou sélectionnez l’option pour créer un compte gratuit.
4. Utilisez l’application de bureau pour ce cours, pas Postman dans un navigateur Web. La version Web ne peut pas joindre 127.0.0.1 sur votre ordinateur sans un programme supplémentaire, le Postman Desktop Agent.

Exemple détaillé : une première requête

L’API d’Amira fonctionne à l’adresse http://127.0.0.1:8000. Dans Postman, elle ouvre un nouvel onglet de requête (le + à côté des onglets ouverts), puis :

1. Elle garde la méthode GET et saisit l’URL http://127.0.0.1:8000/health.
2. Elle sélectionne Send (envoyer).

La réponse apparaît dans la moitié inférieure de la fenêtre :

Partie du panneau de réponse	Contenu affiché
La ligne d’état	200 OK, le temps en millisecondes et la taille
Body (corps)	{"status": "ok"}, mis en forme (Pretty) ou tel que reçu (Raw)
Headers (en-têtes)	Les en-têtes de réponse, comme content-type: application/json

Ensuite, une requête POST avec un corps JSON :

1. Dans un nouvel onglet, choisissez la méthode POST et saisissez http://127.0.0.1:8000/v1/classify.

2. Ouvrez l’onglet Body de la requête. Sélectionnez raw (brut), puis JSON dans la liste à côté.

3. Saisissez le corps :

   {
     "subject": "Charged twice for March",
     "body": "My card was charged two times for the same invoice."
   }

4. Sélectionnez Send. La réponse est 200 OK avec "category": "billing" et "priority": 1.

Quand vous choisissez JSON, Postman ajoute l’en-tête Content-Type: application/json pour vous. Vous le trouverez dans l’onglet Headers de la requête, parmi les en-têtes que Postman ajoute automatiquement.

Importer le document OpenAPI

Saisir chaque requête à la main prend du temps et répète du travail déjà fait. Votre API décrit déjà chaque point de terminaison dans /openapi.json. Postman peut créer une collection à partir de ce document.

1. Sélectionnez Import (importer), près du coin supérieur gauche de l’application.
2. Collez l’URL http://127.0.0.1:8000/openapi.json.
3. Postman reconnaît un document OpenAPI. Choisissez Postman Collection (collection Postman).
4. Sélectionnez View Import Settings (voir les paramètres d’importation). Réglez Folder organization (organisation des dossiers) sur Tags (étiquettes). Les dossiers correspondront ainsi aux sections de Swagger UI.
5. Sélectionnez Import. Une collection nommée Ticket Classifier API (API de classification des billets) apparaît dans la barre latérale.

Ouvrez-la. L’importation a utilisé la documentation que vous avez écrite dans le module 4 :

Dans Postman	Source
Le nom de la collection, Ticket Classifier API	title dans FastAPI(...)
Les dossiers tickets (billets) et health (état de fonctionnement)	Les étiquettes
Les noms des requêtes, comme Classify a support ticket (classer un billet de soutien)	Le summary de chaque route
La description de chaque requête	La description de chaque route
Les exemples enregistrés sous chaque requête	Les réponses documentées, comme 422 avec la structure d’erreur

De bons résumés dans le code donnent maintenant de bons noms dans Postman.

Faire fonctionner les requêtes importées

Deux éléments demandent encore votre attention.

L’URL de base. Ouvrez Classify a support ticket. Son URL est {{baseUrl}}/v1/classify. {{baseUrl}} est une variable : Postman la remplace par une valeur avant d’envoyer la requête. L’importation en a fait une variable de la collection, avec la valeur /. En effet, le document OpenAPI n’indique pas où l’API fonctionne. Définissez-la :

1. Sélectionnez la collection dans la barre latérale et ouvrez son onglet Variables (variables).
2. Réglez la valeur de baseUrl sur http://127.0.0.1:8000 (sans / à la fin).
3. Enregistrez la collection (Ctrl+S, ou Cmd+S sur macOS).

Le corps de la requête. L’importation a rempli le corps à partir du schéma, pas de votre exemple : "subject": "<string>". Cette chaîne est valide et renvoie other (autre). Remplacez-la par un vrai billet et enregistrez la requête. Postman ne conserve pas une modification tant que vous n’enregistrez pas la requête. Un onglet non enregistré affiche un point dans son nom.

Envoyez maintenant List the ticket categories (lister les catégories de billets) et Classify a support ticket. Les deux renvoient 200.

De Postman à curl, et inversement

Une requête Postman se partage facilement sous forme de commande curl, par exemple dans un rapport de bogue. Ouvrez une requête et sélectionnez l’icône Code (code), représentée par </>, à droite. Choisissez cURL. Postman affiche la commande, avec la variable déjà remplacée par sa valeur.

Cela fonctionne aussi dans l’autre sens. Collez une commande curl dans le champ URL. Postman en fait une requête, avec la méthode, les en-têtes et le corps.

Exercice guidé : votre espace de travail

1. Installez Postman, connectez-vous et ouvrez un nouvel onglet de requête.
2. Envoyez GET http://127.0.0.1:8000/health. Trouvez l’état, le temps et l’en-tête content-type dans le panneau de réponse.
3. Importez http://127.0.0.1:8000/openapi.json comme collection Postman, avec des dossiers organisés par étiquettes.
4. Réglez la variable de collection baseUrl sur http://127.0.0.1:8000 et enregistrez la collection.
5. Ouvrez Classify a support ticket, mettez un vrai billet dans le corps, enregistrez la requête et envoyez-la.
6. Ouvrez les exemples enregistrés sous la requête. Trouvez l’exemple pour 422 et comparez-le à la structure d’erreur du module 3.
7. Ouvrez la vue Code et copiez la requête sous forme de commande cURL. Exécutez la commande dans un terminal. (Sur Windows, adaptez-la pour utiliser un fichier de corps, comme dans le module 1.)

À vous de jouer : des requêtes pour chaque ligne

Votre tableau de contrat du module 3 contient des lignes d’échec. Dans le dossier tickets de la collection, créez une requête enregistrée pour chacune. Donnez-lui un nom qui indique ce qu’elle vérifie :

1. Rejeter un sujet vide : {"subject": ""}.
2. Rejeter un champ inconnu : {"subject": "Refund", "colour": "red"}.
3. Rejeter une requête GET sur classify : GET {{baseUrl}}/v1/classify.

Pour copier une requête, utilisez Duplicate (dupliquer) dans son menu (les … à côté de son nom). Envoyez chaque requête et comparez le code d’état et les fields (champs) au tableau.

Afficher ce que vous devriez voir

1. 422, "code": "invalid_request", "fields": ["subject"].
2. 422, "fields": ["colour"], parce que TicketIn interdit les champs supplémentaires.
3. 405, "code": "method_not_allowed".

Dans la leçon 3, vous ajoutez des tests à ces requêtes pour que Postman vérifie les résultats pour vous.

Erreur courante

Impossible d'envoyer la requête : ECONNREFUSED

Symptôme : Postman affiche Could not send request (impossible d’envoyer la requête) et Error: connect ECONNREFUSED 127.0.0.1:8000 (erreur de connexion refusée). Ou la version Web de Postman ne peut pas joindre votre API locale.

Cause : aucun programme n’écoute à cette adresse et sur ce port. Habituellement, l’API ne fonctionne pas ou utilise un autre port. Avec Postman dans un navigateur Web, la requête vient des serveurs de Postman ou de votre navigateur. Elle ne vient pas du terminal de votre ordinateur. Elle ne peut donc pas joindre 127.0.0.1 sans le Desktop Agent.

Solution :

1. Vérifiez le terminal de l’API : fastapi dev doit fonctionner et afficher Uvicorn running on http://127.0.0.1:8000 (Uvicorn fonctionne à cette adresse).
2. Vérifiez baseUrl : le schéma (http, pas https), l’hôte et le port.
3. Utilisez l’application de bureau pour les API locales.

Vérifiez votre compréhension

Après l'importation, l'URL d'une requête est {{baseUrl}}/v1/classify. Son envoi échoue parce que l'URL est invalide. Pourquoi, et où corriger le problème?

Afficher la réponse

{{baseUrl}} est une variable. L’importation l’a réglée sur /, car le document OpenAPI n’indique pas où l’API fonctionne. L’URL devient donc //v1/classify. Réglez baseUrl sur http://127.0.0.1:8000 dans l’onglet Variables de la collection. Dans la prochaine leçon, un environnement Postman conservera plutôt cette valeur. Une seule collection fonctionnera ainsi pour l’API locale et l’API déployée.

Récapitulatif

• Postman est un client API qui conserve les requêtes dans des collections, avec des noms, des dossiers et des exemples enregistrés.
• Utilisez l’application de bureau pour une API sur votre ordinateur.
• Importer /openapi.json crée une collection à partir de votre documentation : les étiquettes deviennent des dossiers, les résumés deviennent des noms de requêtes.
• {{baseUrl}} est une variable. Définissez sa valeur et remplacez les corps <string> générés par de vrais corps.
• La vue Code transforme une requête en commande curl.

Ensuite, vous ferez fonctionner la collection dans plusieurs environnements et vous garderez les secrets à l’extérieur.

Leçon suivante : Collections, variables et environnements