• 4 heures
  • Facile

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 13/06/2024

Utilisez Postman pour formuler vos requêtes

Identifiez les avantages de Postman

Vous savez déjà qu’une API REST implique l’envoi de requêtes du client à l’API, qui passe la requête au serveur, l’API récupère la réponse et la renvoie enfin au client. Dans ce chapitre, nous allons voir comment formuler ces requêtes grâce à Postman

Cette interface graphique est utilisée par de nombreux développeurs. Elle facilite la construction de nos requêtes. C’est donc l’outil idéal pour tester des API sans devoir utiliser de code.

C’est également celui que nous allons utiliser dans ce cours !

OK, mais pourquoi utiliser Postman en particulier ?

Parce que cette interface offre beaucoup d’avantages :

  • Vous pouvez l’utiliser quel que soit le langage avec lequel vous programmez. 

  • Son interface utilisateur est simple : vous effectuez vos requêtes facilement.

  • Vous n’avez pas besoin de savoir coder, ou d’utiliser une application. 

Téléchargez Postman

L’heure est venue de vous lancer : téléchargez Postman

Choisissez votre système d’exploitation. Postman est disponible pour Linux, Windows et OS X. Les instructions sont en anglais. :)

La page d'accueil de Postman : à gauche de l'interface les icônes proposent de télécharger votre système d'exploitation.
La page d'accueil de Postman

Une fois que vous l’aurez fait, vous allez être redirigé sur une page pour télécharger le logiciel. Cliquez sur le bouton Download the App.

Le bouton de téléchargement de Postman pour MacBook
Le bouton de téléchargement de Postman pour MacBook

Parfait ! Et maintenant, passons à la formulation des requêtes. 😃

Formulez une requête sur Postman

La structure d’une requête

Chaque requête a une structure spécifique qui a cette forme :

Verbe HTTP + URI + Version HTTP + Headers + Body (facultatif)

Une structure de requête typique en 3 couches superposées : en bas le body, au milieu les Headers, au-dessus le verbe HTTP, l'URI et la version HTTP.
Une structure de requête typique

L’aspect peut varier en fonction du logiciel ou du langage utilisé.

Visualisez une requête sur Postman

Maintenant que vous avez lancé le logiciel, regardons ensemble à quoi ressemble une requête sur Postman.

Vous devriez avoir cette vue :

Le champ utilisé pour réaliser une requête dans Postman est entouré en vert dans l'onglet Workspaces de l'interface.
Champ utilisé pour réaliser une requête dans Postman

Houlà… c’est un peu compliqué, non ?

Pas de panique, détaillons ensemble chaque zone une à une en suivant la structure d’une requête :

Exemple de verbe HTTP avec GET : affiché à gauche.
Exemple de verbe HTTP avec GET
Le verbe

Commençons avec le verbe. Les verbes HTTP correspondent à différents types d’actions que vous pouvez accomplir avec votre requête. Ceux que vous rencontrerez le plus couramment sont GET (obtenir), PUT (mettre), POST (publier), et DELETE (supprimer). Ne vous y attardez pas trop pour le moment, nous les étudierons tous plus en détail plus tard !

L’URL d’une requête complète comprend le nom de domaine : api.github.com, et l'URI (le chemin de la ressource) : /users/faceboook
L’URL d’une requête complète comprend le nom de domaine : api.github.com, et l'URI (le chemin de la ressource) : /users/faceboook
L’URI

Passons à l’URI. Un URI est le moyen d’identifier les ressources. Par exemple, si vous voulez voir tous les utilisateurs sur votre site web, le path serait le suivant :

/users

OK, mais imaginons que vous vouliez obtenir les informations d’un utilisateur spécifique. Dans ce cas-là, il vous faudrait préciser son ID. On obtiendrait quelque chose comme ceci :

users/:user_id

Pourquoi on utilisait un nombre avant, et tout d’un coup tu nous mets  :user_id ? 🤔

On utilise  :user_id  pour matérialiser l’ID de l’utilisateur, c’est ce qu’on appelle un placeholder. En pratique, avec un ID réel, le path ressemblerait plutôt à ça :  users/145

Les Headers Content-Type et Authorization sont affichés dans une requête.
Headers dans une requête

Un header (ou en-tête) vous permet de faire passer des informations supplémentaires sur le message. Par exemple :

  • De quel langage s’agit-il ?

  • À quelle date l’envoyez-vous ?

  • Quel logiciel la personne utilise-t-elle ?

  • Quelle est votre clé d’authentification ?

Les headers sont représentés par une paire clé et valeur, et il existe de nombreux types d’options différents pour eux. Par exemple :

Date : Mardi 19 Janvier 2019 18:15:41 GMT

Utilisateur-Agent : Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5)

Vous pouvez consulter la liste complète des différentes options pour les  headers.

Le body (ou corps de message, en français) est affiché depuis l'onglet Body de la requête.
Le body (ou corps de message, en français)
Le body

Pour finir, parlons du body ! Pour formuler une requête, il n’est utilisé qu’avec PUT (mise à jour) ou POST (création). Il contient les données réelles de la ressource que vous essayez de créer ou de mettre à jour. Les données sont envoyées sous format JSON.

Petit rappel : le JSON est largement utilisé ; toutefois il se peut que certaines API n’acceptent que le XML. Vous trouverez cette information dans la documentation de l’API que vous utiliserez.

Prenons un exemple ! Vous voulez ajouter ou mettre à jour les informations d’un utilisateur ; vous ajouterez donc les détails de l’utilisateur (prénom, nom , adresse…) dans le body, en JSON.

Notez que le body est facultatif dans ces deux cas. Cela signifie qu’il est tout à fait possible d’envoyer un body vide en fonction des actions de l’API visée.

Vous en apprendrez plus à ce sujet dans les prochains chapitres. 🕵🏻‍♀️

Obtenez une réponse avec Postman

Structure des requêtes ✅ ! Passons aux réponses.

Le format du message de réponse est très similaire à celui de la requête :

Version HTTP + Code de réponse HTTP + Headers + Body

Une structure de réponse typique en 3 couches superposées : en bas le Body, au milieu le Header et au-dessus la version et le code HTTP.
Une structure de réponse typique

Dans Postman, vous verrez un message de réponse comme celui-ci :

Un message de réponse typique de Postman est affiché sur l'interface dans l'onglet Body.
Un message de réponse typique

Attends deux secondes... Le body ? Mais il n'est pas censé être utilisé seulement pour faire une requête avec POST et PUT ? 🤔

Pour formuler une requête, oui ! Mais pour les réponses, le body contient l’information que vous avez demandée, et que l’API vous renvoie. Celle-ci est matérialisée au sein du body sous la forme d’un JSON ou en XML. L’image ci-dessus montre une réponse d’une requête réussie, faite à l’API GitHub. 

Et si elle échoue ? Que se passe-t-il ? On obtient une information différente ? 🤔

Exactement ! Si la requête échoue, le body peut contenir un message d’erreur :

Une requête qui échoue
Une requête qui échoue

Mais le message ne suffit pas, et entre nous il peut arriver que des API n’envoient pas de messages du tout – que la requête soit un succès ou non. Cela peut arriver, même si c’est rare ! Dans ce cas, votre meilleur allié sera le code de réponse HTTP ! 

Analysez le code de réponse HTTP

Le code de réponse HTTP aide le développeur et/ou le client à comprendre le statut de la réponse. Jetons un œil sur les exemples obtenus avec Postman :

Un code de statut HTTP 200 OK pour une requête réussie
Un code de statut HTTP pour une requête réussie
Un code de statut HTTP 404 Not found pour un échec
Un code de statut HTTP pour un échec

Lorsqu’un client vous envoie une requête comme « Salut, pourriez-vous m’envoyer tous les tweets de cet utilisateur ? », vous pouvez vous représenter le code de réponse comme un feu de signalisation 🚥 qui vous dit par exemple :

VERT ✅ : « Cette requête a été traitée avec succès. »

ou

ROUGE 🔴 : « Nous n’avons rien trouvé pour cette requête ! »

Il existe de nombreux codes de réponse différents – vous connaissez probablement le 404 not found (ou introuvable, en français). Vous l’avez peut-être vu sur quelques sites web. Par exemple, si vous essayez d’aller sur une page qui n’existe pas sur GitHub, vous verrez quelque chose comme ça :

Page de réponse 404 GitHub
Page de réponse 404 GitHub

Un autre code de réponse important à connaître est le 200 OK – qui signifie que votre requête a réussi, et que votre réponse est prête ! En général, les règles de base pour les codes de réponse HTTP sont les suivantes :

  • 100+ ➡ Information

  • 200+ ➡ Succès

  • 300+ ➡ Redirection

  • 400+ ➡ Erreur client

  • 500+ ➡ Erreur serveur

Les codes HTTP sont très codifiés, et chaque nombre correspond à une réponse particulière. De ce fait, toutes les API renverront une 404 si la ressource est introuvable, et cela permet aux développeurs de comprendre de quel type de réponse il s’agit. C’est une sorte de nomenclature générale respectée par tous.

Si vous avez un doute sur un code HTTP, n’hésitez pas à consulter cette documentation qui contient de plus amples informations et détails !

En résumé

  • Postman est un logiciel gratuit qui vous permet d’effectuer des requêtes API sans coder.

  • Les requêtes prennent la forme suivante :
    Verbe HTTP + URI + Version HTTP + Headers + Body facultatif.

  • Les verbes HTTP sont des types d’actions que l’on peut faire lors de la formulation d’une requête.

  • Les réponses prennent la forme suivante :
    Code de réponse HTTP + Version HTTP + Headers + Body.

  • Les codes de réponse HTTP sont des sortes de feux de signalisation 🚦 avec des codes spécifiques, pour informer les clients si la requête est un succès ou un échec.

  • Les codes HTTP sont codifiés en fonction du type de réponse ; vous trouverez la liste ici.

Dans le chapitre suivant, nous allons remonter nos manches et commencer à travailler avec de vraies API ! Pour que votre apprentissage soit le plus efficace, il est important de connaître les formats généraux de requêtes et de réponses, ainsi que de savoir à quoi ressemble une réponse réussie ou non !

Exemple de certificat de réussite
Exemple de certificat de réussite