Comment tester et jouer avec les API Web en toute simplicité avec Postman

Dans un monde où les sites Web et les applications statiques dépendent de plus en plus d'API gérées séparément, il peut être difficile de comprendre comment ils fonctionnent en jouant simplement dans le navigateur.

Alors, comment pouvons-nous utiliser Postman pour tester nos API existantes et comprendre comment elles fonctionnent?

  • Qu'est-ce que Postman?
  • Qu'allons-nous construire / apprendre?
  • Partie 0: Mise en place avec Postman
  • Partie 1: Une introduction à Postman
  • Partie 2: Création d'une nouvelle demande de facteur pour obtenir des informations sur Squirtle
  • Partie 3: Création d'une collection de requêtes dans Postman pour la PokéAPI
  • Partie 4: Faire des demandes POST avec Postman pour traduire des phrases comme Yoda
  • Partie 5: Authentification des requêtes auprès de l'API du Seigneur des Anneaux avec une clé API

Qu'est-ce que Postman?

Postman est un outil que les équipes peuvent utiliser pour tester de manière fiable les API à l'aide de configurations faciles à utiliser. Il est livré avec des fonctionnalités auxquelles vous vous attendez lors de l'utilisation d'API, notamment l'authentification, la définition des en-têtes, la personnalisation de la charge utile et bien d'autres encore qui aident à réduire les frictions liées à l'utilisation d'une API.

Et ce n'est pas seulement pour les tests. La beauté est que cela peut être utilisé pour de nombreux aspects du travail avec les API pour de nombreux membres différents de l'équipe. Peut-être qu'un chef de projet veut vérifier que les choses fonctionnent ou trouvera plus facile de faire un changement directement avec l'API, ou un ingénieur QA doit s'assurer que tout fonctionne toujours, ou un développeur veut apporter activement des modifications tout en travaillant sur l'API elle-même .

La meilleure partie à ce sujet - Postman fournit des fonctionnalités de collaboration. Le niveau gratuit comprend l'exportation et l'importation de collections de demandes d'API enregistrées ainsi que la création de liens partagés. Si vous faites partie d'une équipe, ils ont des niveaux payants qui vous permettent de synchroniser vos collections pour vous assurer que tout le monde a la collection la plus récente et à jour.

Qu'allons-nous construire / apprendre?

Nous allons parcourir deux exemples d'API différents pour couvrir les concepts de Postman.

Tout d'abord, nous allons parcourir quelques requêtes HTTP simples avec une API publique pour Pokémon.

Nous utiliserons ensuite l'API Yoda Translator pour une partie pour montrer comment effectuer des requêtes HTTP spécifiques.

Une fois que nous aurons compris le fonctionnement des bases, nous utiliserons l'API du Seigneur des Anneaux pour apprendre comment l'authentification fonctionne avec les API. Pour cela, vous devrez créer un compte gratuit pour une clé API.

Partie 0: Mise en place avec Postman

Avant de commencer, vous aurez besoin de Postman pour suivre cette procédure pas à pas. La bonne nouvelle, c'est que Postman est disponible gratuitement sur Mac, Windows et Linux, vous devriez donc pouvoir trouver une version qui fonctionne pour vous.

Obtenez Postman: //www.postman.com/downloads/

Une fois téléchargé, parcourez les instructions d'installation standard, ouvrez-le et nous devrions être prêts à partir!

Partie 1: Une introduction à Postman

La première fois que vous ouvrez Postman, vous verrez immédiatement un tableau de bord avec un tas d'options pour commencer.

Cela peut sembler un peu écrasant, mais décomposons certains des concepts clés que nous aurons besoin de connaître.

Demandes

Une requête est un peu ce à quoi elle ressemble, c'est une requête API spécifique. Ce sera un type unique de demande, qu'il s'agisse d'un GET ou d'un POST vers un point de terminaison spécifique. Vous voudrez créer de nouvelles demandes pour chaque type de point de terminaison, ce qui vous permettra de vous déplacer entre elles lors du test.

Les collections

Une collection est un groupe de requêtes. Ceci est pratique pour organiser vos demandes en différents groupes. Cela peut être aussi simple que deux API totalement différentes (par exemple, Twitter vs Slack) ou il peut s'agir de deux groupes différents d'API pour une seule API (par exemple, l'API Twitter Tweets vs l'API des comptes Twitter).

Autorisation

L'autorisation est la manière dont les demandes sont authentifiées avec une API, que ce soit par une personne qui fait une demande ou par un ordinateur qui fait cette demande en votre nom. Cela se présente généralement sous la forme d'une clé API qui peut être une valeur statique attribuée à votre compte ou générée dynamiquement avec des outils comme OAuth.

Environnements

Les environnements vous permettront de configurer vos points de terminaison pour utiliser des variables spécifiques qui facilitent l'utilisation des mêmes points de terminaison entre différents environnements. Par exemple, vous pouvez avoir le même /profilepoint de terminaison sur vos environnements de production et de développement, mais ils ont des domaines différents. Les environnements vous permettent de gérer une seule demande avec un domaine variable.

Espaces de travail

Nous n'irons pas trop loin dans les espaces de travail dans cet article, mais cela vous permet de gérer et d'organiser différents ensembles de collections. Imaginez si vous souhaitez utiliser Postman à la fois pour le travail et pour un projet personnel, vous pourriez avoir un espace de travail de travail ainsi qu'un espace de travail personnel.

Pour les besoins de cet article, nous couvrirons les demandes, les collections et l'autorisation.

Partie 2: Création d'une nouvelle demande de facteur pour obtenir des informations sur Squirtle

Maintenant que nous avons une meilleure compréhension des différentes terminologies, créons en fait une requête.

En haut à gauche de l'interface utilisateur, vous devriez voir un bouton orange indiquant Nouveau . Allez-y et cliquez dessus, puis sélectionnez Demande .

Avant d'entrer dans la demande elle-même, il demande quelques choses.

Cette première chose nécessite un nom. Nous allons commencer par demander des informations sur le Pokémon Squirtle, appelons donc ce «Pokémon - Squirtle».

Il nécessite également une collection, alors cliquez sur Créer une collection et nommons la collection «Mon Pokémon préféré».

Cliquez sur le bouton coche orange à côté du nom de la collection, puis appuyez sur Enregistrer .

À ce stade, nous aurons une nouvelle demande, alors construisons cette demande.

Il y a deux choses que nous devons d'abord remplir pour notre première demande:

  • Type de requête: GET, POST, PUT, etc. - nous utiliserons GET
  • URL de la demande: le point de terminaison de votre demande d'API - pour notre demande, nous utiliserons //pokeapi.co/api/v2/pokemon/squirtle/

Et une fois que vous vous êtes assuré que ceux-ci sont corrects, vous pouvez simplement appuyer sur le bouton bleu Envoyer à droite et nous avons fait notre première demande avec succès!

Nous obtenons immédiatement quelques éléments que nous pouvons voir:

  • Corps: en bas, nous devrions maintenant voir le corps de la réponse de la requête API. Pour notre API Squirtle, nous devrions avoir un objet JSON avec des données comme abilities, base_experienceet forms.
  • Statut: à droite, nous devrions voir le code d'état HTTP. «200 Ok» est un bon signe et cela signifie que c'est réussi!
  • Temps: simplement combien de temps la demande a pris pour se terminer
  • Size: la taille en Ko (dans notre exemple) des données de réponse

Vous pouvez également survoler le statut, l'heure et la taille et obtenir un examen plus approfondi de chaque option.

Nous avons donc fait notre première demande!

Une chose à noter avant de passer à autre chose est que notre demande ressemble à celle d'un onglet de navigateur. Si nous en avons terminé avec cette demande particulière, nous pouvons fermer l'onglet et cliquer sur Enregistrer pour nous assurer que toutes nos modifications sont là pour la prochaine fois!

Partie 3: Création d'une collection de requêtes dans Postman pour la PokéAPI

Maintenant que nous avons créé une requête, créons une collection d'entre elles. Techniquement, nous devions déjà créer une nouvelle collection pour la partie 2, mais nous en créerons une nouvelle pour apprendre comment les collections elles-mêmes fonctionnent.

En haut à gauche de l'interface utilisateur, cliquez à nouveau sur le bouton orange Nouveau et sélectionnez Collection .

Semblable à une demande, il demande un nom alors appelons cela «PokéAPI». Vous pouvez éventuellement ajouter une description, puis cliquer sur Créer en bas.

Sur la gauche, vous verrez maintenant votre collection. Vous pouvez sélectionner et développer le dossier puisque nous travaillerons avec lui.

Avant d'ajouter une demande, le PokéAPI a différents types de demandes, il est donc logique de l'organiser un peu plus minutieusement. Alors cliquons sur les trois points à côté de la collection PokéAPI et sélectionnez Ajouter un dossier .

Semblable aux autres, cela demande un nom. Les dossiers sont un peu comme des collections à l'intérieur d'une collection, vous obtenez donc des options similaires. Appelons celui-ci "Pokémon" et cliquez sur le bouton orange Enregistrer comme avant.

Ajoutons maintenant nos demandes! Tout d'abord, cliquez sur les trois points à côté du dossier Pokémon, de la même manière que nous avons ajouté un dossier à la collection, mais cette fois, sélectionnez Ajouter une demande .

Appelons cette requête «Pokémon». Bien qu'il puisse être déroutant que nous ayons une demande Pokémon dans le dossier Pokémon, Pokemon n'est qu'un des points de terminaison du groupe Pokémon.

Maintenant, utilisons la même API exacte que nous avons utilisée avec notre requête Squirtle auparavant:

  • Type de demande: GET
  • URL de la requête: //pokeapi.co/api/v2/pokemon/squirtle/

Et comme avant, lorsque nous appuyons sur le bouton bleu Envoyer , nous devrions voir une demande réussie!

Ajoutons maintenant une autre requête. Suivez le même processus que précédemment pour créer une nouvelle requête dans le dossier PokéAPI Pokémon et nommons cette requête «Capacités».

Si vous faites défiler la réponse du premier point de terminaison Squirtle, vous voyez de nombreuses autres URL d'API. Au sommet, nous en avons abilitieset nous en avons deux différents - «torrent» et «rain-dish».

Choisissez votre capacité Squirtle préférée et copiez la urlvaleur dans la nouvelle demande de capacités que nous venons de créer, je vais l'utiliser rain-dish.

Nous pouvons laisser le type de demande GET, appuyer sur le bouton bleu Envoyer et nous pouvons à nouveau voir une réponse réussie!

Ici, nous obtenons beaucoup d'informations sur notre capacité de Squirtle Rain Dish et certains détails sont disponibles dans différentes langues, ce qui est cool!

Nous avons donc maintenant une nouvelle collection PokéAPI avec un dossier Pokémon représentant le groupe de points de terminaison de l'API Pokémon, y compris les Pokémon et les capacités.

Nous allons arrêter la partie 3 avec ces 2 requêtes, mais n'hésitez pas à continuer et à ajouter autant de requêtes PokéAPI que vous le souhaitez!

Partie 4: Faire des demandes POST avec Postman pour traduire des phrases comme Yoda

Jusqu'à présent, nous n'avons fait que des requêtes GET, mais que faire si nous voulions faire une requête POST où nous devons réellement envoyer des données?

Pour faire une requête POST, nous allons utiliser l'API Yoda Translator de funtranslations.com. Bien que cette API ne prenne qu'un seul paramètre, c'est toujours un bon point de terminaison public que nous pouvons utiliser pour comprendre le concept.

Commençons par créer une nouvelle collection avec une nouvelle requête:

  • Collection: Traductions amusantes
  • Demande: Yoda

Cette fois, au lieu d'une requête GET, notre configuration de requête sera:

  • Type de demande: POST
  • URL de la demande: //api.funtranslations.com/translate/yoda

Maintenant, cette fois, si nous appuyons sur le bouton bleu Envoyer , nous remarquerons que nous n'obtenons pas une réponse 200 réussie, nous obtenons un 400!

Nous n'avons jamais configuré de données à publier sur l'API et cela nécessite ces données, alors ajoutons-les.

Juste en dessous de l' URL de la demande , cliquez sur Corps . Ensuite, au lieu de rien, sélectionnez brut comme type de corps. Enfin, à l'extrême droite des types, remplacez Text par JSON .

Ensuite, dans l'espace en dessous, vous pouvez ajouter ce qui suit:

{ "text": "Hello, I am learning how to test APIs with Postman!" } 

Et maintenant, cliquez à nouveau sur le bouton bleu Envoyer et nous obtenons une réponse réussie!

Nous pouvons appliquer ce concept à pratiquement toutes les API. Postman ne vous permet pas seulement de publier JSON, il vous permet d'utiliser les autres formats que nous voyons répertoriés dans la section Type de corps, ce qui signifie que vous avez beaucoup d'options en fonction de ce que l'API que vous utilisez nécessite.

Partie 5: Authentification des requêtes auprès de l'API du Seigneur des Anneaux avec une clé API

Pour le reste de la procédure pas à pas, nous allons utiliser l'API Lord of the Rings.

Tout d'abord, l'API du Seigneur des Anneaux nécessite une authentification afin de faire des requêtes à l'aide d'une clé API. Donc, pour commencer, vous allez avant de plonger, vous devrez créer un compte gratuit.

//the-one-api.herokuapp.com/sign-up

Une fois que vous vous êtes inscrit et connecté, la première chose que vous verrez est votre clé API! Copiez cette clé vers le bas ou rappelez-vous où vous pouvez la trouver pour plus tard. Si vous quittez la page, vous pouvez toujours la saisir en accédant à Bienvenue , puis à Compte dans la navigation du site Web de l'API.

Pour commencer, créons d'abord une nouvelle collection et demandons:

  • Collection: Seigneur des anneaux
  • Dossier: Film
  • Demande: tous les films
  • Type de demande: GET
  • URL de la demande: //the-one-api.herokuapp.com/v1/movie

Une fois que vous êtes configuré avec ce qui précède, cliquez sur Envoyer , et vous remarquerez immédiatement qu'il donne une réponse qui dit 401 et qu'il n'est pas authentifié.

Étant donné que cette API nécessite la clé API, c'est exactement ce à quoi nous nous attendions. Alors cliquons sur l' onglet Autorisation . Nous pouvons ensuite sélectionner un type de jeton porteur , et sur la droite, nous pouvons coller notre clé que nous venons de configurer avec l'API du Seigneur des Anneaux.

Et dès que nous appuyons sur Envoyer , nous voyons maintenant une réponse réussie!

Cela a très bien fonctionné, mais que se passe-t-il si nous avons un tas de demandes qui utilisent une seule clé. Devons-nous gérer cela à chaque demande?

Au lieu de le gérer à chaque demande individuelle, nous pouvons le gérer sur la collection. Commençons par créer une autre requête.

Sous notre collection Le Seigneur des Anneaux et dans le dossier Film, créez une nouvelle requête:

  • Demande: devis par identifiant de film
  • Type de demande: GET
  • URL de la demande: //the-one-api.herokuapp.com/v1/movie/{id}

Dans cette demande, utilisons un ID de la réponse de la première demande, je vais utiliser 5cd95395de30eff6ebccde5bqui est l'ID de The Two Towers, donc l'URL de la demande ressemblera à:

//the-one-api.herokuapp.com/v1/movie/5cd95395de30eff6ebccde5b

Maintenant, au lieu de définir notre jeton dans la demande d'autorisation, nous allons laisser le type comme Inherit auth from parent . Cliquez sur les trois points à côté de la collection et sélectionnez Modifier .

Ici, nous allons faire exactement la même chose que nous avons fait avec la première requête mais sur la configuration de la collection. Sélectionnez l' onglet Autorisation , sous type, sélectionnez Bearer Token , et dans le champ Token , collez à nouveau votre token.

Enfin, cliquez sur Mettre à jour et appuyez à nouveau sur le bouton bleu Envoyer et nous pouvons voir une demande réussie!

Nous pouvons maintenant revenir à notre demande Tous les films et mettre à jour l'autorisation d'utiliser un type d'authentification hérité du parent et cela devrait continuer à fonctionner!

Que pouvons-nous faire d'autre avec Postman?

Bien que j'aie couvert beaucoup de bases, vous pouvez faire beaucoup plus avec Postman. Voici quelques un de mes préférés.

Variables d'environnement

Si vous travaillez en tant que développeur sur un projet, il est probable que votre équipe utilise plusieurs environnements, tels qu'un environnement de développement et de production. Au lieu de créer et de maintenir des requêtes complètement séparées, vous pouvez ajouter une variable d'environnement et modifier à la place cette variable lors du passage d'un environnement à l'autre!

Les variables s'appliquent à de nombreux scénarios, mais c'est une utilisation courante. Consultez la documentation de Postman pour savoir comment.

//learning.postman.com/docs/postman/variables-and-environments/variables/

Importer et exporter des collections et des données

Une grande chose à propos de Postman est qu'une fois que vos demandes sont toutes organisées, vous pouvez les exporter pour que d'autres les utilisent. Cela signifie également que vous pouvez importer des collections d'autres membres de l'équipe. Cela rend beaucoup plus facile de s'assurer que tout le monde utilise la même collection.

Bonus: vous pouvez même stocker ces fichiers dans un référentiel Git, car ils ne sont que JSON.

Mais gardez à l'esprit que si vous utilisez l'autorisation sur la collection comme nous l'avons vu dans ce guide, vous voudrez vous assurer de ne pas l'inclure lors de l'exportation de votre collection.

//learning.postman.com/docs/postman/collections/importing-and-exporting-data/

Test automatisé

Une fois que vous avez un ensemble de demandes dans une collection et encore mieux, si vous les stockez dans Github, vous pouvez commencer à utiliser ces demandes dans le cadre d'un moyen de gérer les tests automatisés de votre API.

Bien qu'il existe quelques solutions pour ce faire, Postman inclut un exécuteur de collection intégré directement dans l'application et Newman est un outil de ligne de commande qui vous permet d'exécuter des tests directement depuis le terminal.

//www.postman.com/use-cases/api-testing-automation/

Quelle est votre façon préférée de tester et de jouer avec les API?

Partagez avec moi sur Twitter!

Suivez-moi pour plus de Javascript, UX et d'autres choses intéressantes!

  • ? Suis moi sur Twitter
  • ? ️ Abonnez-vous à mon Youtube
  • ✉️ Inscrivez-vous à ma newsletter