Présentation de Postman
Crée en 2012 comme un plugin de navigateur dans le but de faciliter les processus de tests d’une API, Postman s’est imposé comme une plateforme de référence. Disponible via une interface web ou un client, ce logiciel est un incontournable dans le développement d’une API pour son site ou son application. Il est utilisable gratuitement, mais propose des offres payantes avec de nombreuses fonctionnalités et intégrations. On peut réaliser une documentation de son API et la partager en ligne pour les autres utilisateurs. Ainsi on peut retrouver des collections d’APIs de services très connus comme Slack, Microsoft Graph, Notion qui sont faites par ces entreprises ou des utilisateurs de la plateforme.
Postman propose la création d’un environnement de test pour créer des variables à utiliser dans les requêtes. Ceci est très pratique pour préenregistrer le nom d’utilisateur, l’id secret, un JSON ou un mot de passe qui sera appelé dans plusieurs requêtes. On peut aussi monitorer des tests dans le temps pour vérifier les performances de son serveur et les surcharges. Enfin la partie d’identification auprès d’un serveur est assez poussée avec de nombreux types de connexions pris en charge (Basic Auth, Bearer Token, OAuth, etc.). Pour utiliser la web application, il est recommandé d’installer l’agent Postman qui permet de contourner les limitations des navigateurs sur le cross-origin.
La tableau de bord
Après avoir créé un compte, on arrive sur le tableau de bord qui est assez simple et clair. Il résume son activité, les derniers workspaces visités, les dernières collections mises à jour, etc. Pour revenir sur le tableau de bord il faut cliquer sur Home à gauche dans le menu de navigation. L’onglet Workspaces regroupe tous les espaces de travail de son compte. Un workspace est un ensemble de collections, d’APIs, de variables d’environnement, etc. que l’on peut utiliser pour un ou plusieurs projets et qu’il est possible de partager.
Configurer un workspace
En créant un workspace, il faut définir un nom, une description et la visibilité. Les modes Privé et Partenaire sont réservés aux offres payantes. Le mode Public permet de partager les informations avec tous les utilisateurs de Postman. Choisir un mode de visibilité Personnel pour commencer et s’il est nécessaire de collaborer avec d’autres utilisateurs, il est possible de changer le mode en le passant plus tard en Équipe.
Une fois l’espace de travail créé, nous arrivons sur son espace dédié. À gauche nous retrouvons les collections, les APIs, les variables et les autres éléments qui sont enregistrés dans ce workspace. Et à droite, via le système d’onglet, est accessible l’interface de requête de Postman. L’onglet actif est Overview qui présente un résumé de l’espace de travail actuellement ouvert. Il est possible de fermer l’onglet pour avoir une interface vide.
Faire une requête vers une API
Pour tester une requête dans Postman, nous allons utiliser une API en accès libre qui est celle de la base de données des entreprises proposée par le gouvernement. L’adresse de l’API est https://recherche-entreprises.api.gouv.fr et le endpoint pour rechercher est search. Dans Postman au niveau de la zone de gauche se rendre dans environnements puis cliquer sur +, cela ouvre un nouvel onglet pour renseigner les variables que l’on souhaite utiliser dans cet environnement. Indiquer un nom à l’environnement et renseigner la variable url avec la valeur https://recherche-entreprises.api.gouv.fr/search qui contient le endpoint pour communiquer avec l’API.
Ensuite, ouvrir un nouvel onglet et sélectionner l’environnement précédemment créé en haut à droite de l’interface. Cela va permettre d’utiliser ces informations dans plusieurs requêtes afin de rechercher des entreprises de différentes façons puis d’enregistrer les requêtes. Indiquer au niveau de l’URL la variable utilisée en mettant {{url}} puis dans Params indiquer la clé q avec comme valeur La+Poste par exemple. Automatiquement l’URL va se renseigner avec les bons paramètres.
À gauche de la barre de l’URL, on peut définir la méthode (GET, POST, PUT, etc.). Les exemples de cet article se focalisent sur la méthode GET classique qui permet de récupérer les résultats. Une fois la requête prête à être envoyée, il suffit de cliquer sur le bouton Send et la réponse s’affichera dans la zone réponse un peu plus bas dans l’interface. Le petit cercle orange dans l’onglet juste à côté du nom indique que la requête n’est pas enregistrée.
Dans la zone des résultats, Postman affiche directement la sortie au bon format suivant le header. Dans cette réponse nous pouvons visualiser toutes les entreprises dont le nom commercial est La Poste avec différentes informations. Tout en bas du JSON, on trouve le nombre de résultats que nous renvoie l’API ainsi que la page courante et le nombre de pages.
Créer une collection
Pour sauvegarder la requête, il suffit de cliquer sur le bouton Save en haut à droite. Il faut indiquer un nom puis choisir une collection ou en créer une nouvelle afin de regrouper les requêtes. On peut créer la collection API Entreprise qui contiendra les différentes requêtes proposées dans cet article.
Après avoir sauvegardé la requête, nous allons en créer une nouvelle pour rechercher les entreprises dans le secteur de la programmation informatique du département des Hautes-Pyrénées. Le numéro du département est le 65 et le code NAF à rechercher est 62.01Z. Pour cela on créé un nouvel onglet avec toujours dans l’URL la variable {{url}} puis on indique dans Params les clés departement et activite_principale avec les valeurs que l’on souhaite.
Une plateforme de qualité
Postman est un excellent outil qui est facile à prendre en main pour tester une API durant la phase de développement. La version gratuite permet de réaliser de simples tests et propose d’explorer les différentes collections. Sans un tel outil, nous devons faire les tests manuellement avec curl en codant des fonctions ce qui prend bien plus de temps. La version gratuite est limitée à 3 utilisateurs pour les espaces de travail en équipe au-delà il faut passer sur une offre payante proposant plus de fonctionnalités et des intégrations vers différentes plateformes.