Notes et transcriptions du cours “Adoptez les API REST pour vos projets web” disponible sur la plateforme Openclassrooms

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 !

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 :

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.

GitHub est une plateforme qu’utilisent les développeurs pour stocker leur code et travailler seul ou en équipe. Cela permet de faciliter la collaboration entre développeurs d'un même projet. En tant que développeur, vous l’utiliserez beaucoup ! Si vous êtes curieux de connaître son fonctionnement, allez voir le cours Gérez du code avec Git et GitHub.

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 !

Interface utilisateur Postman

Interface utilisateur Postman avec 3 encadrés :

• En haut à gauche, un menu déroulant encadré en noir
• En-dessous : le bouton Params encadré en rouge
• A droite du bouton : l'onglet Headers encadré en bleu

• 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 de l'API 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 !

La documentation nous apprend plusieurs choses :

1. Cette section fournit les informations disponibles publiquement sur quelqu’un ayant un compte GitHub.
2. On peut accéder aux informations d’un utilisateur via GET /users/:username.
3. Un exemple de réponse est fournit

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).

La requête GET est entourée en vert et contient une adresse HTTP.

Requête GET

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 !

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.

Rappelez-vous, en JSON, la réponse est affichée sous un format clé-valeur.

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  !

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.

Documentation de l’API Ghibli.

A gauche, les réponses renvoyées par l'API sont affichées, à droite la réponse s'affiche sous forme d'array.

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.herokuapp.com/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é.

Chaque fois que vous voulez utiliser une API, commencez par consulter la documentation.

• 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.

◁ Précédent | ⌂ Retour au sommaire | Suivant ▷