Les premiers pas

La première fois que vous ouvrez Postman, il vous demandera de vous connecter. Si vous n'avez pas encore de compte Postman, il est fortement recommandé de vous inscrire. Vous pouvez ignorer la connexion, mais la création d'un compte est totalement gratuite, ce qui facilite grandement la gestion et le partage de votre travail. Une fois que vous êtes connecté, vous verrez l'écran principal avec un tas d'options différentes pour les choses que vous pouvez faire avec Postman.

Configurer une requête dans Postman

Il est temps de configurer un appel API afin que nous puissions le disséquer et voir comment tout cela fonctionne. Vous pouvez le faire en procédant comme suit :

• Commencez par cliquer sur le bouton «+» sur le bloc Requests :



• Pour ce premier exemple, on utilise l'API GitHub, alors vous pouvez le nommer quelque chose comme Get User Repos.
• Postman organise les requêtes en collections, vous devrez donc également créer une collection dans laquelle vous pourrez entreposer la requête. Faites défiler la boîte de dialogue vers le bas et cliquez sur le lien Create Collection :
  
• Nommez la collection quelque chose comme Github API Requests et cliquez sur la coche pour choisir cette collection comme endroit où vous entreposerez la requête que vous faites.
• Maintenant, cliquez sur le bouton Save dans la boîte de dialogue.

Vous serez redirigé vers un onglet où vous pourrez remplir les détails de la demande. Il y a quelques éléments différents étant réunis pour faire une requête d'API.

La structure d'une requête API

L'onglet de requête dans Postman fournit de nombreuses informations sur les différents éléments composant une requête d'API. Chacun de ces éléments joue un rôle important dans l'envoi et la réception de données avec une API, et je vais donc vous guider à tour de rôle. Certaines parties d'une requête API sont facultatives en fonction du type de requête et de ce que vous essayez d'en faire, mais deux éléments sont requis pour chaque requête API. Chaque demande d'API a besoin d'un point de terminaison et d'une action.

Points de terminaison de l'API

Chaque demande d'API basée sur le Web doit spécifier un point de terminaison. Dans l'onglet Request de Postman, vous êtes invité à entrer l'URL de la requête. Postman vous demande de saisir une URL car un point de terminaison d'API n'est qu'une URL (URL est un acronyme pour Uniform Resource Locator). Le point de terminaison d'un appel d'API spécifie la ressource, ou le "R" de l'URL. En d'autres termes, un point de terminaison d'API est le localisateur uniforme d'une ressource particulière avec laquelle vous souhaitez interagir sur le serveur. Les URL vous aident à localiser les ressources sur un serveur et sont donc utilisées comme points de terminaison dans un appel d'API.

Renseignez le champ dans l'onglet de requêtes en saisissant l'URL suivante : https://api.github.com/users/gladir/repos. Ce point de terminaison vous donnera des informations sur mes référentiels sur GitHub. Si vous avez votre propre compte GitHub, vous pouvez mettre votre nom d'utilisateur dans la partie de l'URL où il est écrit gladir et récupérer des données pour vos propres référentiels.

Vous verrez souvent un point de terminaison d'API spécifié sans la partie de base de cette API. Ainsi, par exemple, si vous consultez la documentation de l'API de GitHub, elle signalera le point de terminaison pour cela sous la forme /users/:username/repos. Tous les appels d'API de GitHub commencent par la même URL de base (en d'autres termes, https://api.github.com), et donc cette partie du point de terminaison est souvent omise lorsqu'on parle d'un point de terminaison. Si vous voyez des points de terminaison d'API répertoriés qui commencent par un / au lieu de http ou www, n'oubliez pas que vous devez rechercher l'URL de base de l'API pour le point de terminaison afin de l'appeler.

Actions d'API

Chaque appel d'API doit spécifier une ressource avec laquelle nous travaillons. C'est le point de terminaison, mais il y a une deuxième chose dont chaque appel d'API a besoin. Une API doit faire quelque chose avec la ressource spécifiée. Nous spécifions ce que nous voulons qu'une API fasse avec les actions d'API. Ces actions sont parfois appelées verbes, et elles indiquent à l'appel d'API ce que nous attendons qu'il fasse avec la ressource que nous lui avons donnée. Pour certaines ressources, seules certaines actions sont valides, tandis que pour d'autres, il peut y avoir plusieurs actions d'API valides différentes.

Dans Postman, vous pouvez sélectionner l'action souhaitée à l'aide du menu déroulant à côté de la zone de texte dans laquelle vous avez entré l'URL. Par défaut, Postman définit l'action sur GET, mais si vous cliquez sur la liste déroulante, vous pouvez voir qu'il existe de nombreuses autres actions disponibles pour les appels d'API. Certaines de ces actions sont spécialisées pour des applications particulières, et vous ne les rencontrerez donc pas très souvent. En général, on utilise que GET, POST, PUT et DELETE. De nombreuses API utilisent également PATCH, OPTIONS et HEAD, mais leur utilisation est très similaire à l'utilisation des quatre généralement utilisé, et vous pourrez donc facilement comprendre comment les utiliser si vous les rencontrez. Les autres actions de cette liste ne sont pas souvent utilisées et vous ne les rencontrerez probablement pas beaucoup dans les applications que vous testez et créez.

Les quatre actions (GET, POST, PUT et DELETE) sont parfois résumées avec l'acronyme CRUD. Cela signifie Create (créer), Read (lire), Update (mettre à jour) et Delete (supprimer). Dans une API, l'action POST est utilisée pour créer de nouveaux objets, l'action GET est utilisée pour lire des informations sur les objets, l'action PUT est utilisée pour modifier des objets existants et l'action DELETE est utilisée pour supprimer des objets. En pratique, avoir une API prenant en charge tous les aspects de CRUD vous donne la flexibilité de faire presque tout ce dont vous pourriez avoir besoin, c'est pourquoi ces quatre actions sont les plus courantes que vous verrez.

Les actions d'API et les points de terminaison sont requis pour les API Web, mais nous prendrons en compte plusieurs autres éléments importants des requêtes d'API.

Paramètres de l'API

Les paramètres de l'API sont utilisés pour créer une structure et l'ordre dans une API. Ils organisent des choses similaires ensemble. Par exemple, dans l'appel de l'API que nous examinons, nous obtenons les référentiels pour un utilisateur particulier dans GitHub. Il existe de nombreux utilisateurs dans GitHub, et nous pouvons utiliser exactement le même point de terminaison de l'API pour obtenir la liste des référentiels pour l'un d'eux avec le changement de nom d'utilisateur dans le point de terminaison. Cette partie du point de terminaison où elle accepte différents noms d'utilisateur est un paramètre.

Requête des paramètres

Le paramètre de nom d'utilisateur dans l'API du dépôt GitHub est connu comme un paramètre de requête. Vous pouvez considérer un paramètre de requête comme une chaîne de remplacement dans le point de terminaison de l'API. Ils sont très courants dans les API Web. Vous les verrez représentés de différentes manières dans la documentation des différentes API. Par exemple, la documentation GitHub utilise un caractère de deux-points (:) devant le paramètre de requête pour indiquer qu'il s'agit d'un paramètre de requête et pas juste d'une autre partie du point de terminaison. Vous verrez des points de terminaison spécifiés comme celui-ci dans la documentation GitHub «:/user/:username/repos».

Dans d'autres API, vous verrez à la place des paramètres de requête enfermés dans des accolades bouclées. Dans ce cas, le point de terminaison ressemblerait à «/user/{{username}}/repos». Quel que soit le format utilisé, le point de requête des paramètres est d'obtenir des informations particulières sur différents objets étant tous du même type. Vous pouvez le faire avec ce point de terminaison en remplaçant le nom d'utilisateur (username) par votre nom d'utilisateur (ou tout autre nom de l'utilisateur de GitHub).

Paramètres de requête

Il existe un autre type de paramètre que vous pouvez avoir dans un point de terminaison de l'API. Ce type de paramètre est connu comme un paramètre de requête et il est un peu plus difficile à gérer. Un paramètre de requête agit souvent comme un type de filtre ou une action supplémentaire que vous pouvez appliquer à un point final. Ils sont représentés par un point d'interrogation dans le point de terminaison de l'API et sont spécifiés avec une clef étant l'élément pour lequel vous interrogez, et une valeur, c'est ce que vous voulez que la requête revienne.

Ce point de terminaison prend en charge quelques paramètres de requête différents. L'un d'eux est le paramètre de type. Afin d'ajouter des paramètres à un point de terminaison de l'API dans Postman, assurez-vous que l'onglet Params est sélectionné, puis mettez le nom du paramètre de requête dans le champ de clef et la valeur dans le champ de valeur. Dans ce cas, nous utiliserons le paramètre de type, alors entrez ce mot dans le champ de clef.

Pour ce point de terminaison, le paramètre de type nous permet de filtrer selon que vous êtes propriétaire d'un référentiel ou simplement d'un membre. Par défaut, le point de terminaison ne renverra que les référentiels dont vous êtes propriétaire, mais si je veux voir tous les référentiels dont je suis membre, je peux mettre un membre dans le champ de valeur pour cela. À ce stade, la requête devrait ressembler à ceci :

Si vous envoyez cette requête, elle récupère tous les référentiels du membre gladir, par opposition à ceux qu'il possède.

Entêtes API

Chaque requête d'API doit inclure certains entêtes. Les entêtes incluent certaines des informations générales n'étant souvent pas si importantes pour les utilisateurs humains, mais ils aident le serveur à avoir des informations sur le client envoyant la requête. Parfois, nous devrons modifier ou ajouter certains entêtes afin d'obtenir une API pour faire ce que nous voulons, mais souvent nous pouvons simplement laisser l'outil que nous utilisons envoie les entêtes par défaut qu'il doit envoyer sans s'en soucier.

Dans Postman, vous pouvez voir quels entêtes seront envoyés avec votre requête en utilisant l'onglet Headers. Vous pouvez également modifier les entêtes et en ajouter des autres ici au besoin.

Corps de l'API

Si vous souhaitez créer ou modifier des ressources avec une API, vous devrez donner au serveur des informations sur le type de propriétés que vous souhaitez que la ressource ait. Ce type d'informations est généralement spécifié dans le corps d'une requête.

Le corps de la requête peut prendre de nombreux formats. Si vous cliquez sur l'onglet Body dans la requête Postman, vous pouvez voir certains des différents types de données que vous pouvez envoyer. Vous pouvez envoyer des données à partir de données, des données de formulaire codées, des données brutes, des données binaires et même des données GraphQL. Comme vous pouvez l'imaginer, il y a beaucoup de détails entrant dans l'envoi de données dans le corps d'une requête. La plupart du temps, les requêtes ne vous obligent pas à spécifier un corps. D'autres types de requêtes, tels que POST et PUT, qui vous obligent à spécifier un corps, nécessitent souvent une forme d'autorisation car ils vous permettent de modifier des données.