Bonjour !
Dans la leçon précédente, nous avons posé les fondations théoriques des API REST. Vous avez découvert ce qu'est une requête, une réponse, une méthode HTTP et le format JSON. Ces concepts sont le "vocabulaire" nécessaire pour faire communiquer des systèmes entre eux.
Aujourd'hui, nous passons de la théorie à la pratique. L'objectif est de vous rendre capable d'utiliser un outil essentiel, Postman, pour envoyer vous-même des requêtes à une API et analyser ce que vous recevez en retour. C'est une compétence fondamentale qui vous permettra de tester et de comprendre n'importe quelle API avant de l'intégrer dans Genesys Cloud sous forme de Data Action. Pensez à Postman comme un simulateur qui vous permet de valider vos appels en toute sécurité avant de les construire dans votre flux Architect.
1. Qu'est-ce que Postman et comment l'installer ?
Postman est une application qui vous donne une interface graphique pour construire et envoyer des requêtes HTTP sans écrire une seule ligne de code. C'est le "client" parfait pour dialoguer avec un "serveur" API.
Le schéma ci-dessous résume le processus : vous préparez votre requête dans Postman, vous l'envoyez, le serveur API la traite et Postman vous affiche la réponse.
Pour commencer, nous allons installer Postman et nous familiariser avec son interface.
Débuter avec Postman et les Requêtes API
La vidéo 'Débuter avec Postman et les Requêtes API' de la chaîne Test&Code by marieBouvard est un excellent guide pour vos premiers pas. Nous allons l'utiliser pour l'installation et la découverte de l'outil.
Veuillez suivre les étapes présentées dans la vidéo : Installation (00:29 - 03:54) : Téléchargez et installez Postman. La création d'un compte gratuit est recommandée pour sauvegarder votre travail. Découverte de l'interface (03:54 - 05:30) : Prenez quelques instants pour repérer les éléments principaux de l'interface. Création d'un Espace de Travail (Workspace) et d'une Collection (05:30 - 09:43) : Suivez les instructions pour créer un "Workspace" (ex: "Formation Genesys") et une "Collection" (ex: "Tests API Publiques"). C'est une bonne pratique pour organiser vos requêtes.
Une fois Postman installé et votre première collection créée, vous devriez voir une interface similaire à celle-ci. Prenez un moment pour identifier les zones clés que nous allons utiliser :
2. Envoyer votre première requête GET
Maintenant que l'outil est prêt, nous allons envoyer notre première requête. Nous utiliserons une API publique très connue appelée JSON Placeholder. Elle simule une API de blog et est parfaite pour s'entraîner car elle ne nécessite aucune authentification.
Notre premier objectif : récupérer la liste de tous les articles ("posts") disponibles.
Débuter avec Postman et les Requêtes API
Continuons avec la vidéo de Test&Code. Cette section vous guide pas à pas pour créer et envoyer une requête GET simple.
Regardez de 09:43 à 16:23. Suivez les étapes pour : Ajouter une nouvelle requête à votre collection. Configurer l'URL sur https://jsonplaceholder.typicode.com/posts. Laisser la méthode sur GET et envoyer la requête. Observer la réponse obtenue.
Vous avez réussi ! Vous venez de communiquer avec un serveur via une API. Analysons maintenant ce que vous avez reçu en retour dans la partie "Response" de Postman :
- Le Statut : Vous devriez voir un statut
200 OK. Comme nous l'avons vu dans la leçon précédente, un code de la série 2xx signifie que tout s'est bien passé. - Le Corps (Body) : Postman vous présente la réponse au format JSON, bien formatée et colorée. Vous pouvez voir que la réponse est un tableau (indiqué par les crochets
[...]). Chaque élément du tableau est un objet JSON (indiqué par les accolades{...}) représentant un article, avec ses propres paires clé-valeur ("userId","id","title","body").
Cette structure est exactement ce que vous devrez interpréter dans Genesys Cloud pour extraire, par exemple, le titre d'un article.
3. Affiner la requête avec des paramètres
Récupérer une centaine d'articles à chaque fois n'est pas très efficace. La plupart du temps, vous voudrez filtrer les résultats. Pour cela, on utilise des paramètres de requête (query parameters). Ils sont ajoutés à la fin de l'URL et permettent de passer des informations au serveur pour qu'il affine sa réponse.
Imaginons que nous voulions récupérer uniquement les commentaires associés à l'article n°1 (postId=1).
Débuter avec Postman et les Requêtes API
La section suivante de la vidéo montre précisément comment utiliser les paramètres pour filtrer une requête.
Regardez de 16:23 à 20:44. Suivez les instructions pour créer une nouvelle requête (ou dupliquer la précédente) afin de récupérer les commentaires. Portez une attention particulière à : Le changement d'URL vers https://jsonplaceholder.typicode.com/comments. L'utilisation de l'onglet Params pour ajouter la clé postId avec la valeur 1. L'analyse de la réponse, qui ne contient que les commentaires pour le postId demandé.
L'onglet Params de Postman est très pratique, car il construit l'URL pour vous. Si vous regardez la barre d'adresse, vous verrez qu'elle est devenue https://jsonplaceholder.typicode.com/comments?postId=1. C'est cette URL complète que la requête utilise réellement.
La maîtrise des paramètres est cruciale, car c'est ainsi que vous passerez des informations dynamiques (comme un numéro de client ou un identifiant de dossier) depuis votre flux Architect vers une API externe via une Data Action.
Pour aller plus loin (Optionnel)
Nous nous sommes concentrés sur la méthode GET, qui sert à lire des données. C'est la plus courante pour les Data Actions qui récupèrent des informations. Sachez qu'il en existe d'autres, notamment :
POSTpour créer une nouvelle donnée (ex: créer un ticket dans un CRM).PUT/PATCHpour mettre à jour une donnée existante.DELETEpour supprimer une donnée.
Si vous êtes curieux de voir comment fonctionne une requête POST, la vidéo ci-dessous l'illustre avec une autre API amusante.
C'est quoi une API REST ? S'initier aux API avec Postman !
La vidéo 'C'est quoi une API REST ?' de Bertrand . Tech montre un exemple de requête POST pour envoyer du texte à une API de traduction.
Regardez de 10:31 à 13:46. Notez la principale différence avec GET : la requête POST envoie des données dans l'onglet Body de la requête, et pas seulement dans l'URL.
Conclusion
Excellent travail ! Vous avez fait un grand pas en passant de la théorie à la pratique. Vous êtes maintenant capable d'utiliser Postman pour interroger une API et comprendre sa réponse.
Voici les points clés à retenir :
- Postman est un outil indispensable pour tester des API de manière visuelle et sans code.
- Une requête
GETpermet de lire des données depuis une URL spécifique. - La réponse d'une API contient un code de statut (ex:
200 OK) et un corps (souvent en JSON) contenant les données. - Les paramètres de requête (Query Params) permettent de filtrer et de personnaliser les données que l'on souhaite recevoir.
Cette compétence va considérablement accélérer votre travail avec les Data Actions. Au lieu de tester directement dans Genesys Cloud, vous pourrez d'abord valider chaque appel dans Postman, vous assurer que la requête est correcte et comprendre la structure exacte de la réponse avant de la configurer dans Architect.
Prochaine leçon :
Maintenant que vous savez comment interroger manuellement une API, nous allons configurer Genesys Cloud pour qu'il puisse le faire. Dans la prochaine leçon, nous allons créer et configurer votre première intégration "Web Services Data Actions". C'est la porte d'entrée qui permettra à Genesys Cloud de dialoguer avec le monde extérieur.