Améliorez votre API grâce à Postman

Documentation, tests, monitoring, mock... Tour d'horizon de Postman

13 oct. 2020 à 08:08 – 18min


Table des matières

Bonjour et bienvenue dans ce nouvel article qui va traiter d'un outil indispensable pour les développeurs : Postman ! Vous connaissez déjà sûrement ce logiciel qui vous permet de tester vos APIs, mais savez-vous que Postman propose une multitude de fonctionnalités qui vous aideront à simplifier vos développements ? Nous parlerons ici de documentation, de tests, de monitoring, de serveurs de mocks, et bien plus encore.

Dans cet article, je vais prendre pour exemple l'API de Github, afin que nous puissions tous travailler sur les mêmes bases. Bien évidemment, je vous encourage à tester les fonctionnalités que je vous présenterai ici sur vos propres projets. Si vous souhaitez, comme moi, travailler avec l'API de Github, il vous faudra obtenir un token d'authentification. Comme ce n'est pas le sujet de cet article, je vous invite plutôt à suivre la documentation officielle de Github afin d'obtenir ce token (vous n'aurez besoin que des droits user et repo). Bien sûr, si ce n'est pas déjà le cas, il vous faudra également télécharger Postman

Environnement et variables

Avec Postman, vous pouvez définir plusieurs environnements afin de travailler différemment selon votre projet. Dans notre exemple, nous allons créer un nouvel environnement propre à notre API, qui contiendra notamment plusieurs variables que nous utiliserons au fil de notre avancement. À noter que ces variables seront sauvegardées sur votre compte Postman, mais ne sont pas visibles lorsque vous partagez votre travail, à la manière des fichiers et des variables d'environnement que vous pourriez utiliser dans vos applications.  

Pour créer un nouvel environnement, rien de plus simple. Dans Postman, cliquez sur le bouton "+ New", puis "Environment". En haut de la popup, donnez un nom à votre environnement. Pour ma part, je choisis "Github demo". En dessous, vous pouvez définir sous forme de tableau vos variables d'environnement. Ici, je vais définir trois variables pour commencer : 

Ainis, votre environnement devrait ressembler à ceci : 

Création d'un environnement sur Postman

Ne vous en faites pas, la clé d'API sur la capture d'écran n'existe plus ;)

Collections et requêtes

Créer une nouvelle collection

Afin de pouvoir travailler correctement, nous allons devoir créer une collection. Sur Postman, une collection est une sorte de dossier qui contiendra toutes nos requêtes.  

Rentrons dans le vif du sujet. Lancez Postman, appuyez sur le gros bouton "+ New", puis choisissez "Collection". Dans le premier onglet, nous allons indiquer le nom que l'on souhaite attribuer à notre collection, ainsi qu'une brève description. Dans l'onglet "Authorization", nous allons indiquer à Postman comment s'authentifier auprès de l'API pour l'ensemble de nos requêtes. Dans notre cas, il s'agit d'une authentification de type "Bearer Token". Dans le champ "token", ne collez pas directement votre clé d'API ! Nous avons créé une variable d'environnement pour cela, vous pouvez simplement indiquer la valeur "{{ token }}". 

Configuration des paramètres d'authentification d'une collection sur Postman

Vous pouvez maintenant valider. Votre première collection est créée !  

Ajouter des requêtes

Dans cette collection, nous allons maintenant ajouter notre première requête. Cliquez de nouveau sur le bouton "+ New", puis choisissez "Request". Là encore, nous pouvons donner un titre et une description à notre requête. En général, nous choisissons comme titre le préfix d'URL de la requête, c'est-à-dire sans le schéma et le domaine. Ici je vais choisir "/users", qui correspond à un appel à https://api.github.com/users. 

Exemple de requête Postman

 

Configurer vos requêtes

Maintenant, vous devez configurer votre nouvelle requête en indiquant dans un premier temps la méthode HTTP à utiliser ainsi que l'URL. Nous définissons ici définir la requête /users qui utiliser la méthode GET et qui aura comme URL {{ base_url }}/users  

C'est l'occasion pour moi de vous parler des différents paramètres que vous pouvez donner à votre requête. Ceux-ci sont affichés sous le champ URL de la fenêtre. 

Vous pouvez maintenant tester votre requête en cliquant sur "Send" (ou avec le raccourci ctrl+enter ou cmd+enter).

Exemple de réponse dans Postman

La réponse s'affiche alors sur la partie droite de Postman, au format Json. Vous pouvez remarquer qu'au-dessus de la réponse se trouvent un certain nombre d'informations utiles, comme le code HTTP reçu, le temps de réponse, et la taille de la réponse. Vous pouvez également choisir d'afficher la réponse dans différents formats. En général, vous choisirez "Pretty" pour afficher du Json, ou "Preview" pour du HTML. 

Par ailleurs, vous pouvez également choisir d'afficher les informations reçues autres que le body, comme les cookies ou headers, via le menu déroulant au-dessus de la réponse. 

N'hésitez pas à parcourir l'interface et les différentes possibilités offertes par Postman en créant d'autres requêtes. La documentation de Github est très fournie, et vous ne devriez pas avoir de mal à vous amuser un peu avec !

Documentez votre API

Publier la documentation

Maintenant que nous avons quelques requêtes dans notre collection, nous allons voir comment la documenter efficacement pour pouvoir travailler en équipe. Pour cela, rien de plus simple. Faites un clic droit sur votre collection, puis sélectionnez "publish docs". Une page web s'ouvre afin de configurer notre documentation. Vous pouvez laisser les paramètres par défaut. Assurez-vous seulement de bien sélectionner "No environment" dans le champ "Environment", afin de ne pas partager vos variables sensibles au public. Vous pouvez également désélectionner l'option "Collection discovery" qui rendra votre documentation visible sur les moteurs de recherche. Vous pouvez maintenant sauvegarder votre configuration, et Postman vous proposera une URL vers votre documentation. 

Je vous l'accorde, notre documentation est assez vide pour l'instant. Allons la remplir un peu. 

Pour commencer, essayez d'ajouter une nouvelle requête qui utilise la méthode POST. Pour notre exemple, je vais ajouter une nouvelle requête capable de créer un repository sur notre compte Github. Notre requête aura donc comme URL {{base_url}}/users/repos, et le body suivant au format raw/json :

Votre requête devrait donc ressembler à ceci :

Requête pour créer un nouveau repository Github dans Postman

Notez que l'on peut également utiliser nos variables d'environnement dans le body de notre requête. Essayez d'exécuter cette requête, vous devriez maintenant voir sur votre compte Github un nouveau repository ! 

Nous allons maintenant faire la même chose pour supprimer notre repository. Ajoutez encore une requête DELETE qui aura comme URL {{base_url}}/repos/{{username}}/{{repo_name}}

Attention ! Supprimer un repository est irréversible ! Je vous conseille fortement d'utiliser une variable d'environnement ici afin d'être sûr de ne pas vous tromper !

Vous pouvez maintenant sauvegarder votre collection via un simple ctrl+S (ou cmd+S sur Mac). En une fraction de seconds, votre documentation en ligne est mise à jour !

Ajouter des exemples 

En général, quand on documente une API, on aime bien offrir des exemples à nos utilisateurs. Heureusement, Postman nous aide à créer des exemples pour nos requêtes très rapidement ! Pour ajouter un nouvel exemple à une requête, cliquez sur le bouton "examples" au-dessus du bouton "Send". Par défaut, Postman va reprendre l'ensemble des paramètres de la requête et de la réponse (à condition de l'avoir déjà exécutée) afin de préremplir notre nouvel exemple. Enfin, n'oubliez pas d'indiquer un nom à votre exemple. En général, je crée un exemple pour chaque code HTTP de réponse possible, et j'indique ce code dans le nom de l'exemple. Ici, j'indique donc "201 Created".

Création d'un nouvel exemple sur Postman

Validez, puis sauvegardez vos changements. Votre nouvel exemple devrait maintenant s'afficher sous la requête dans votre documentation !

Autres options de documentation

Vous l'avez peut-être déjà remarqué, mais il est possible de décrire n'importe quel paramètre ou header de votre requête. Je vous invite à le faire pour tous vos paramètres, ainsi que pour les headers qui ne sont pas explicites (inutile de décrire le header Host par exemple). Les descriptions apparaîtront également dans votre documentation en ligne, et pourront aider vos utilisateurs à comprendre le fonctionnement de votre API.

Enfin, je n'en ai pas parlé jusqu'à maintenant, mais il est possible d'utiliser le format Markdown pour documenter votre API. Par exemple, essayez d'éditer votre collection, puis ajouter le contenu suivant dans votre description :

Testez votre API

Ecrire des tests

Maintenant que nous avons défini quelques requêtes pour notre API, il est temps de les tester !

Nous allons ici tester la requête qui permet de créer un nouveau repository, afin de vérifier que le repository créé respecte bien les paramètres indiqués dans la requête. Pour cela, rendez-vous dans l'onglet "tests" de la requête, et ajoutez le code Javascript suivant : 

Comme vous pouvez le voir, les tests Postman sont écrits en Javascript. Même si vous n'êtes pas très à l'aise avec ce langage, vous pouvez voir que l'exemple ci-dessus est assez trivial. On utilise la fonction pm.test afin de valider les éléments de l'objet Json de la réponse. Chaque test correspond à une condition qui doit être respectée pour que le test soit validé.

En cas d'erreur, vous pouvez consulter la console intégrée à Postman en cliquant sur le bouton "Console" en bas à gauche de votre écran.

Étant donné que les tests sont écrits en Javascript, il est bien évidemment possible de faire des choses bien plus complexes que ce que je vous montre ici. N'hésitez pas à essayer par vous-même !

Exécuter et tester une suite de requêtes

Postman propose également un "Runner", c'est-à-dire un système permettant de lancer une suite de requêtes et de tests de votre collection dans un certain ordre. N'attendons plus et testons cela par nous-même. 

Pour commencer, cliquez sur le bouton "Runner" en haut à gauche de la fenêtre. Dans le panneau de gauche, sélectionnez la collection que vous souhaitez tester, sans oublier d'indiquer l'environnement à injecter. Vous pouvez également définir d'autres options, comme le nombre d'itérations ou le délai entre chaque requête, mais nous n'en auront pas besoin ici.

Dans le panneau de droite, sélectionnez les requêtes que vous souhaitez utiliser et mettez-les dans l'ordre. Dans notre exemple, nous voulons d'abord créer un repository avant de le supprimer, et non l'inverse. 

Cliquez maintenant sur le bouton "Run Postman Demo". Après quelques secondes, les informations sur les requêtes ainsi que les tests effectués devraient s'afficher. 

Exemple de Runner sur Postman

Dans notre exemple, Postman a d'abord appelé la requête pour créer notre repository, effectué les tests que nous avons ajouté plus haut, puis supprimé le repository. Vous pouvez maintenant voir la puissance et l'utilité de l'automatisation de nos tests !

Monitorer une collection

Postman permet également de monitorer l'exécution de nos appels successifs ainsi que de nos tests, afin de les rendre visibles en ligne. 

Dans le menu contextuel de votre collection, sélectionnez "Monitor Collection". Dans la fenêtre de configuration qui s'affiche, vous pouvez laisser les paramètres par défaut, puis valider. 

Postman devrait maintenant ouvrir pour vous l'onglet "Monitor" de votre API, dans lequel vous pouvez cliquer sur le lien vers votre nouveau Monitor afin de l'ouvrir en ligne. Sur cette nouvelle page, vous pouvez maintenant cliquer sur le bouton "run" afin de lancer votre runner directement en ligne. Les résultats au fil du temps sont affichés sur la page, avec la progression du temps d'exécution.

Postman Monitor

Créer un mock de l'API

Commençons par créer un nouveau serveur de mock en utilisant le bouton "+ New" de Postman. Dans la fenêtre de configuration qui s'affiche, vous pouvez lister les URLs de votre serveur une par une, mais nous allons plutôt utiliser la collection que nous venons de créer ensemble en cliquant sur l'onglet "Select an existing collection". Dans la fenêtre suivante, cochez la case "Save the mock server URL as an environment variable" afin de créer une nouvelle variable d'environnement qui contiendra l'URL de notre serveur. Attention, si vous souhaitez rendre votre serveur privé, il vous faudra utiliser une clé d'API Postman comme expliqué dans la documentation officielle

Une fois le serveur créé, Postman vous proposera une URL que vous devrez copier afin de mettre à jour la variable d'environnement base_url. Et voilà, si vous essayez de lancer votre runner, vos tests devraient toujours passer, sauf que maintenant nous passons par un serveur mocké et non plus par l'API de Github !

Vous pouvez également observer les logs du serveur directement en ligne, en sélectionnant votre serveur sur Postman :

Logs du mock server Postman