Dans le chapitre précédent, nous avons parlé des verbes HTTP et de la façon dont ils permettent de réaliser des actions spécifiques lors de la formulation d’une requête API. Rappelez-vous, j’avais mentionné GET, POST, PUT et DELETE. Eh bien, il est temps d’en apprendre un peu plus, et surtout de les utiliser ! 🙌
Découvrez le CRUD
Le CRUD est la liste des actions de base que vous pouvez effectuer sur une ressource. C’est un acronyme qui signifie Create (créer), Read (lire), Update (mettre à jour), et Delete (supprimer). Bien que le CRUD ne constitue pas vraiment un mécanisme technique en soi, chaque action CRUD est associée à un verbe HTTP. Voici la cartographie :
Action CRUD | Verbe HTTP associé |
Create (Créer) | POST (Publier) |
Read (Lire) | GET (Obtenir) |
Update (Mettre à jour) | PUT (Mettre) |
Delete (Supprimer) | DELETE (Supprimer) |
Obtenez des résultats avec votre première requête GET
Maintenant que nous avons vu tout le contexte qui se cache derrière une API, il est temps de pratiquer ! 🏋️♀️ Utilisons une API pour obtenir des données. Nous utiliserons le verbe HTTP GET et l’API GitHub (de GitHub) pour obtenir des données sur un utilisateur GitHub spécifique.
Pour faire une requête sur l’API, utilisons le logiciel Postman que vous avez téléchargé précédemment.
Prêt ? Allons- y ! 🚀
Commencez par ouvrir le programme.
Nous l’avions survolé lors du dernier chapitre, mais il est toujours bon de revoir ce que nous avons appris. Détaillons un peu ce que nous voyons, de haut en bas ! 🕵️
La première ligne (encadrée en noir) vous permet de sélectionner votre type de requête dans le menu déroulant (dans notre cas, ce sera GET) 🤫.
À côté, vous pouvez remplir la case avec l’URL complète de votre requête.
Il y a un petit bouton (encadré en rouge) nommé Params. Si vous cliquez dessus, vous aurez un emplacement pour définir les valeurs clés de vos paramètres.
À droite (encadré en bleu), vous pouvez cliquer sur Headers. Cela vous permettra de définir vos headers de requête.
Et pour finir, en dessous, en jaune , vous pouvez voir l’emplacement du body de votre réponse.
Nous voulons obtenir des informations sur un utilisateur. Mais comment faire ? Quelle URL utiliser ? 🤔
Avant de faire une requête sur l’API GitHub et d'obtenir un utilisateur en particulier, vous devez avant tout faire une chose très importante : consulter la documentation GitHub ! Et plus précisément la section Users, car c’est celle-ci qui nous intéresse. La documentation, c’est le mode d’emploi d’une API. C’est ainsi que vous trouverez les ressources, URI et endpoints que vous pouvez utiliser pour récupérer des données.
Allez sur la section Users de l’API GitHub via cette URL : https://developer.github.com/v3/users/
La partie qui nous intéresse ici est celle qui nous permet d’obtenir un seul utilisateur (Get a user en anglais). Cliquez dessus !
Voici ce que dit la documentation en français :
Obtenir un utilisateur unique
Fournit les informations disponibles publiquement sur quelqu’un ayant un compte GitHub.
Les applications GitHub avec la permission utilisateur Plan peuvent utiliser cet endpoint pour récupérer des informations sur le plan GitHub d’un utilisateur. L’application GitHub doit être authentifiée en tant qu’utilisateur. Voir « Identifier et autoriser les utilisateurs pour les applications GitHub » pour plus de détails sur l’authentification. Pour un exemple de réponse, voir « Réponse avec l’information du plan GitHub ».
La clé e-mail dans la réponse ci-dessous correspond à votre adresse e-mail visible publiquement depuis votre page de profil GitHub. Lors de la création de votre profil, vous pouvez sélectionner une adresse e-mail principale comme « publique », ce qui fournit une entrée e-mail pour cet endpoint. Si vous ne choisissez pas d’adresse e-mail publique pour e-mail, alors sa valeur sera nulle. Vous ne voyez que les adresses e-mail visibles publiquement lorsque vous êtes authentifié dans GitHub. Pour plus d’informations, voir Authentification.
L’API Emails vous permet de lister toutes vos adresses e-mail, et d’ajouter un toggle à une adresse e-mail principale pour qu’elle soit visible publiquement. Pour plus d’informations, voir « API Emails ».
La documentation nous apprend plusieurs choses :
Cette section fournit les informations disponibles publiquement sur quelqu’un ayant un compte GitHub.
On peut accéder aux informations d’un utilisateur via GET /users/:username.
Un exemple de réponse :
Parfait ! 🙌
Si on résume, cela signifie que, pour obtenir la donnée user de l’utilisateur “tenderlove” (oui oui c’est un vrai login, cet homme existe et est d’ailleurs un des contributeurs de Ruby on Rails 👌), vous allez dans Postman et entrez https://api.github.com/users/tenderlove dans l’URL, puis appuyez sur Send (Envoyer).
Et voilà ! Vous avez effectué votre première requête GET avec succès !
Vous pouvez remplacer tenderlove par votre login GitHub et observer la réponse. 😉 N’hésitez pas à comparer les données récupérées par l’API et celles de GitHub : vous verrez, ce sont les mêmes !
Voici comment faire en vidéo :
GET est le verbe HTTP le plus utilisé. Il permet de faire une requête afin de récupérer un groupe de données mais aussi des données précises. Comme vous l’avez vu avec l’API GitHub, avec une requête GET vous allez obtenir des données précises grâce à un ID ; dans notre exemple, votre nom d’utilisateur GitHub. Notez la façon dont votre navigateur (ou client) utilise une API pour afficher les données sur un site web. Ici, la réponse est sous un format JSON.
Vous pouvez même effectuer des requêtes GET directement depuis votre navigateur, car les endpoints REST utilisent le même protocole HTTP que le web. Essayez d’aller sur https://api.github.com/users/tenderlove maintenant, et vous verrez !
Utilisez la documentation pour connaître le mode d’emploi de l’API
Comme vous pouvez le constater, la documentation d’une API ressemble à un manuel d’utilisation très très détaillé. Étant donné que chaque API est différente, vous ne sauriez pas les utiliser sans une documentation claire et précise.
Quelles informations nous donne cette documentation ? ✋
La documentation liste tous les appels API possibles, les requêtes et réponses typiques, mais surtout les verbes à utiliser pour chaque requête. Cette API Ghibli constitue un bon exemple.
Dans cet exemple, pour récupérer tous les films Ghibli, vous voyez qu’il vous suffit de faire une requête GET sur https://ghibliapi.vercel.app/#tag/Films. Vous avez aussi une indication sur les messages d’erreur que renvoie l’API en cas de mauvais format de la requête (400) ou d’absence de ressources trouvées (404). Vous voyez aussi qu’en cas de succès, vous obtiendrez une réponse sous forme d’un array (ou tableau) qui contiendra la liste des films Ghibli. Un exemple de cette donnée se trouve sur la droite dans l’encadré.
En résumé
CRUD signifie create (créer), read (lire), update (mettre à jour) et delete (supprimer).
GET est le verbe HTTP pour obtenir des données, et il est généralement utilisé avec un ID pour obtenir une donnée spécifique.
Les applications utilisent GET pour présenter des informations sur des pages web.
Utilisez Postman pour tester les API.
La documentation est le manuel d’utilisation d’une API.
La documentation vous permet de trouver la liste des endpoints accompagnée du verbe HTTP correspondant.
Que ce soit à des fins personnelles ou professionnelles, utiliser une API c’est utiliser des données. Ces données sont parfois sensibles et il est important de les sécuriser. Abordons à présent un élément que je considère comme ultra important : la sécurité des données et l’authentification.
