Démarrer avec Postman

Publié le 15 juin 2023 par Andrew Owen (4 minutes)

J’ai déjà écrit sur les API REST, mais jusqu’à présent, je n’ai pas abordé la façon la plus simple de commencer à interagir avec elles. Créé par Abhinav Asthana en 2012 dans le cadre d’un projet parallèle visant à simplifier les tests d’API, Postman compte aujourd’hui plus de 25 millions d’utilisateurs enregistrés. Je suppose que vous connaissez déjà les API REST. Si ce n’est pas le cas, je vous propose un article d’introduction sur le sujet.

Postman est disponible sous la forme d’une application web ou d’un téléchargement pour Linux, macOS et Windows. Je préfère utiliser l’application de bureau. Quel que soit votre choix, la première chose à faire est de créer une collection. Il s’agit d’un ensemble portable de données sur l’API avec laquelle vous interagissez, y compris l’autorisation, les URL et les points de terminaison. Si l’API que vous souhaitez utiliser dispose d’un schéma Swagger ou OpenAPI, la manière la plus simple de créer une collection est d’importer le schéma.

Dans le menu principal, sélectionnez Fichier > Importer et faites glisser votre fichier de schéma sur la boîte de dialogue. Sélectionnez Postman Collection et cliquez sur Import. Si vous souhaitez modifier l’API, vous pouvez sélectionner OpenAPI avec une collection Postman. Mais pour les besoins de cet article, je m’en tiendrai à l’utilisation d’un schéma existant. Si vous n’avez pas de schéma, vous devrez créer une collection avec File > New > Collection.

Si vous avez importé un schéma, une grande partie de la configuration sera déjà faite pour vous. Mais si vous avez créé une collection à partir de zéro, commencez par cliquer sur Ajouter une requête dans le menu Actions ( … ) de la collection. Cliquez sur l’onglet Variables de la collection pour éditer les variables globales. Si elles n’existent pas déjà, créez une variable appelée baseUrl avec la valeur https://{{instance}}.example.com/api/v2 où example.com/api/v2 est le chemin vers l’API. Créez ensuite une variable appelée instance avec le sous-domaine. Pour les API publiques, il ne peut y avoir qu’un seul sous-domaine.

Si vous créez la collection à partir de zéro, vous pouvez maintenant utiliser {{baseUrl}}/endpoint/ comme URL pour chaque méthode, où endpoint est le point d’extrémité de l’API auquel vous souhaitez vous connecter. Par exemple, {{baseUrl}}/search/. Si vous avez importé un schéma, ces éléments devraient être pré-remplis.

La prochaine chose à faire est de configurer l’autorisation dans l’onglet Autorisation de la collection. Les API publiques peuvent ne pas nécessiter d’autorisation, auquel cas vous pouvez sélectionner No Auth dans la liste Type. Le type d’autorisation le plus courant est l’autorisation de base. Il se présente sous la forme d’un Username et d’un Password encodés en Base64 (séparés par deux points dans l’en-tête de la requête HTTP).

Mais il se peut que vous ayez à traiter avec une API qui encode nom d'utilisateur:mot de passe comme une seule chaîne de caractères. Si c’est le cas, vous devrez faire l’encodage Base64 vous-même. Sous Linux et macOS, vous pouvez encoder et décoder Base64 avec echo "username:passowrd" | base64 et echo "BASE64_ENCODED_STRING" | base64 -D respectivement. Avec Windows PowerShell, la commande d’encodage est la suivante:

[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))

et la commande de décodage est la suivante

[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('BASE64_ENCODED_STRING'))

Dans l’onglet Autorisation de la collection, sélectionnez No Auth. Ensuite, dans l’onglet Script pré-requête, ajoutez:

pm.request.headers.add({
  key: "Authorization",
  value: "Basic BASE64_ENCODED_STRING"
});

Ceci ajoute l’en-tête à chaque requête de la collection.

Maintenant, si vous avez importé un schéma, vous pouvez commencer à essayer les points de terminaison. Dans la collection, cliquez sur un endpoint pour voir ses paramètres. La documentation de l’API devrait vous indiquer quels Params sont nécessaires et quel contenu est valide dans le Body. Vous pouvez les compléter dans les onglets. Les paramètres sont une paire clé/valeur. Le corps peut être du texte brut, du JavaScript, du HTML ou du XML. Mais le plus souvent, il s’agit de JSON. Postman vous donne la possibilité d’appliquer différents formats au contenu du corps.

Si vous avez importé un schéma, le corps devrait être pré-rempli. Si ce n’est pas le cas, vous devriez pouvoir copier-coller l’exemple de code à partir de la documentation de l’API. Il convient de noter que si vous enregistrez vos modifications, vous remplacerez la valeur par défaut. Postman est un outil incroyablement puissant et un article de blog n’a pas la prétention d’entrer dans les détails. Votre prochain arrêt pour plus d’informations devrait donc être le Centre d’apprentissage.