Tester une API REST avec Postman

1. Qu'est-ce que Postman et comment l'installer ?

Postman est un client HTTP graphique qui simplifie considérablement l'interaction avec les API. Plutôt que d'utiliser des lignes de commande complexes ou de devoir construire une interface utilisateur, Postman nous offre un environnement complet pour créer, envoyer et analyser des requêtes HTTP.

Pour bien commencer, la vidéo suivante vous présente l'outil, son rôle et le lien fondamental entre les méthodes HTTP et les opérations CRUD que nous avons implémentées.

Maintenant que vous avez une vision d'ensemble, nous allons installer Postman. Vous pouvez utiliser la version de bureau (recommandé) ou la version web.

2. Organiser son travail dans Postman : Workspaces et Collections

Une fois Postman installé, la première bonne pratique est d'organiser son espace de travail. Postman utilise deux concepts clés pour cela :

• Workspace (Espace de travail) : Un conteneur de haut niveau pour un projet ou un ensemble de projets. Vous pourriez avoir un workspace pour votre travail professionnel et un autre pour vos projets personnels.
• Collection : Un dossier qui regroupe un ensemble de requêtes liées à une API spécifique. C'est ici que nous allons sauvegarder toutes nos requêtes pour l'API de gestion de livres.

La création d'une structure organisée dès le début vous fera gagner un temps précieux.

Mise en pratique :

1. Dans Postman, créez un nouveau Workspace. Nommez-le "Formation Java Backend".
2. À l'intérieur de ce workspace, créez une nouvelle Collection. Nommez-la "API Livres".

Toutes les requêtes que nous créerons dans cette leçon seront sauvegardées dans cette collection.

3. Testons notre API de gestion de livres !

Le moment est venu de mettre notre API à l'épreuve. Assurez-vous que votre application Spring Boot est démarrée et s'exécute sur localhost:8080.

Nous allons tester chaque endpoint CRUD un par un, en vérifiant à la fois les cas de succès ("happy paths") et les cas d'erreur que nous avons méticuleusement gérés dans les leçons précédentes.

L'article suivant, de Developpez.com, montre comment tester une API Spring Boot avec Postman. Nous allons suivre une démarche similaire.

a) GET /api/books - Récupérer la liste des livres

C'est la requête la plus simple. Elle ne nécessite ni corps (body) ni paramètre complexe.

1. Dans votre collection "API Livres", cliquez sur "Add a request".
2. Nommez la requête "Récupérer tous les livres".
3. Vérifiez que la méthode HTTP sélectionnée est GET.
4. Dans le champ URL, entrez : http://localhost:8080/api/books
5. Cliquez sur Send.

Vous devriez voir une réponse avec :

• Status : 200 OK.
• Body : Un tableau JSON (probablement vide si votre base de données est réinitialisée à chaque démarrage).

b) POST /api/books - Créer un nouveau livre

Cette requête est plus intéressante car elle nécessite un corps (body) contenant les données du livre à créer.

1. Créez une nouvelle requête dans votre collection, nommez-la "Créer un livre".
2. Changez la méthode pour POST.
3. URL : http://localhost:8080/api/books
4. Allez dans l'onglet Body, sélectionnez raw et choisissez JSON dans le menu déroulant.
5. Dans la zone de texte, insérez le JSON suivant :

   {
       "title": "L'Écume des jours",
       "author": "Boris Vian",
       "publicationYear": 1947
   }
   

6. Cliquez sur Send.

Résultat attendu :

• Status : 201 Created.
• Body : Le JSON du livre qui vient d'être créé, avec son id attribué par la base de données.

Maintenant, testons notre validation ! Essayez d'envoyer la même requête POST mais avec un corps invalide, par exemple un JSON vide {}.

Résultat attendu :

• Status : 400 Bad Request.
• Body : Le JSON structuré des erreurs de validation que nous avons configuré !

  {
      "author": "Le nom de l'auteur ne peut pas être vide",
      "publicationYear": "L'année de publication est obligatoire",
      "title": "Le titre ne peut pas être vide ou contenir uniquement des espaces"
  }
  

Ceci confirme que notre GlobalExceptionHandler et nos annotations @Valid fonctionnent parfaitement.

c) GET /api/books/{id} - Récupérer un livre spécifique

1. Récupérez l' id du livre que vous venez de créer.
2. Créez une requête GET nommée "Récupérer un livre par ID".
3. URL : http://localhost:8080/api/books/{id} (remplacez {id} par le vrai ID, ex: http://localhost:8080/api/books/1).
4. Cliquez sur Send.

Résultat attendu :

• Status : 200 OK.
• Body : Le JSON du livre demandé.

Testons la gestion d'erreur 404 : Essayez maintenant avec un ID qui n'existe pas (ex: 999).

• Résultat attendu : Status 404 Not Found avec notre message d'erreur personnalisé.

d) PUT /api/books/{id} - Mettre à jour un livre

La méthode PUT est similaire à POST, mais elle cible une ressource existante pour la mettre à jour.

1. Créez une requête PUT nommée "Mettre à jour un livre".
2. URL : http://localhost:8080/api/books/{id} (utilisez l'ID du livre créé).
3. Dans l'onglet Body (raw, JSON), entrez les nouvelles données. PUT remplaçant la ressource, vous devez fournir tous les champs.

   {
       "title": "L'Écume des jours",
       "author": "Boris Vian",
       "publicationYear": 1946
   }
   

4. Cliquez sur Send.

Résultat attendu :

• Status : 200 OK.
• Body : Le JSON du livre avec l'année de publication mise à jour.

e) DELETE /api/books/{id} - Supprimer un livre

Cette opération est simple mais destructrice.

1. Créez une requête DELETE nommée "Supprimer un livre".
2. URL : http://localhost:8080/api/books/{id} (utilisez l'ID du livre que vous voulez supprimer).
3. Cliquez sur Send.

Résultat attendu :

• Status : 204 No Content.
• Body : Le corps de la réponse est vide, ce qui est normal pour une suppression réussie.

4. Bonne pratique : les variables d'environnement

Vous avez peut-être remarqué que nous avons répété http://localhost:8080 dans chaque requête. C'est une mauvaise pratique. Que se passera-t-il lorsque vous déploierez votre application sur un serveur de test ou de production ? Vous devrez modifier toutes les URL à la main.

Postman résout ce problème avec les variables d'environnement.

Mise en pratique :

1. Dans le panneau de gauche de Postman, cliquez sur Environments, puis créez un nouvel environnement que vous nommerez "Local".
2. Dans cet environnement, créez une variable baseUrl.
3. Dans la colonne INITIAL VALUE, donnez-lui la valeur http://localhost:8080.
4. Sauvegardez l'environnement.
5. En haut à droite de l'interface Postman, assurez-vous que votre environnement "Local" est bien sélectionné.
6. Retournez dans vos requêtes et remplacez http://localhost:8080 par {{baseUrl}}. Par exemple : {{baseUrl}}/api/books.

Désormais, pour changer d'environnement (développement, production), il vous suffira de changer l'environnement actif dans Postman, et toutes vos requêtes pointeront vers la bonne URL.

Conclusion

Félicitations ! Vous maîtrisez maintenant les bases de Postman, un outil essentiel de votre panoplie de développeur backend.

Points clés à retenir :

• Postman est un client HTTP qui permet de tester les API de manière simple et visuelle.
• L'organisation via les Workspaces et les Collections est une bonne pratique pour maintenir vos projets de test.
• Vous savez désormais comment forger des requêtes GET, POST, PUT, et DELETE pour tester toutes les facettes d'une API CRUD.
• Le plus important : vous avez vérifié que votre API réagit correctement non seulement aux cas de succès (statuts 2xx), mais aussi aux erreurs prévues comme les données invalides (400) et les ressources non trouvées (404).
• L'utilisation des variables d'environnement rend vos collections de tests réutilisables et professionnelles.

Nous avons maintenant construit et validé une API REST complète pour une seule entité. Dans le prochain module, nous allons commencer le grand projet de synthèse en modélisant et implémentant des relations entre plusieurs entités JPA, comme @ManyToOne et @OneToMany. Votre maîtrise de Postman sera votre meilleur allié pour développer et déboguer cette API plus complexe.