Chapitre 02 — Faites vos premiers appels API5 min de lecture

Comment fonctionnent les API

Le modèle du restaurant

La meilleure façon de comprendre comment fonctionnent les API est de penser à un restaurant.

Vous (le client) êtes assis à une table. Vous n'entrez pas dans la cuisine pour préparer votre propre repas. Au lieu de cela, vous regardez le menu, choisissez ce que vous voulez et le dites au serveur. Le serveur (l'API) apporte votre commande à la cuisine (le serveur), qui prépare le plat et vous le renvoie par l'intermédiaire du serveur.

C'est tout. C'est ainsi que fonctionnent les API :

  1. Vous envoyez une requête. "Je voudrais les pâtes." En termes d'API : "Donne-moi l'utilisateur avec l'ID 8421."
  2. Le serveur la traite. La cuisine vérifie ce que vous avez demandé, le prépare et le dépose dans une assiette.
  3. Vous recevez une réponse. Le serveur apporte votre plat. En termes d'API : vous recevez un objet JSON avec les données de l'utilisateur.

Vous ne voyez jamais la cuisine. Vous ne savez pas comment les pâtes sont préparées. Vous savez simplement quoi demander et ce que vous recevrez en retour. C'est exactement ainsi que les logiciels communiquent avec les API.

Client, serveur, requête, réponse

Mettons des noms sur les choses. Ces quatre mots reviendront sans cesse.

Client : celui qui demande. Il peut s'agir d'une application mobile, d'un site web, d'un serveur backend ou même d'un tableur avec un plugin. Tout ce qui envoie une requête est un client.

Serveur : celui qui répond. Il reçoit la requête, effectue un travail (recherche de données, traitement d'un paiement, envoi d'un e-mail) et renvoie une réponse.

Requête : la question. "Quelles sont les permissions d'Alice ?" ou "Crée une nouvelle commande" ou "Annule cet abonnement". Une requête va toujours du client vers le serveur.

Réponse : la réponse. Il s'agit généralement d'un objet JSON contenant les données que vous avez demandées, ou une confirmation que l'action a été effectuée. Une réponse va toujours du serveur vers le client.

Chaque interaction API suit ce modèle. Uber demande des directions à Google Maps : requête. Google Maps renvoie l'itinéraire : réponse. Airbnb demande à SendGrid d'envoyer un e-mail : requête. SendGrid confirme l'envoi : réponse.

Les Endpoints : le menu

Dans un restaurant, le menu vous indique ce que vous pouvez commander. Dans une API, l'équivalent est une liste d'endpoints (points de terminaison).

Un endpoint est une URL spécifique qui effectue une action précise. Considérez chaque endpoint comme un plat sur le menu :

  • https://api.myapp.com/users → renvoie la liste de tous les utilisateurs
  • https://api.myapp.com/users/8421 → renvoie le profil de l'utilisateur n°8421
  • https://api.myapp.com/orders → renvoie toutes les commandes
  • https://api.myapp.com/orders/5678 → renvoie les détails de la commande n°5678

Chaque URL pointe vers une ressource spécifique. Vous ne pouvez pas demander quelque chose qui n'a pas d'endpoint. S'il n'y a pas d'URL /invoices, vous ne pouvez pas obtenir de factures. Lorsque vous évaluez un service tiers, la liste des endpoints vous indique exactement ce que l'API peut et ne peut pas faire.

C'est pourquoi la lecture de la documentation de l'API est importante. C'est le menu.

Essayez par vous-même

Un endpoint n'est qu'une URL. Et une URL, vous savez comment en ouvrir une.

wttr.in est un service météo gratuit qui expose une API publique. Pas de compte, pas de clé, pas de configuration. Vous lui donnez un nom de ville dans l'URL, il vous renvoie les données météo au format JSON. Parfait pour nos besoins.

Cliquez sur le lien ci-dessous. Il s'ouvrira dans un nouvel onglet :

👉 https://wttr.in/paris?format=j1

Vous devriez voir un mur de JSON. Ne vous inquiétez pas de la taille. Regardons ce que vous pouvez reconnaître. Quelque part dans la réponse, vous trouverez un objet current_condition avec des valeurs comme :

{
  "temp_C": "15",
  "temp_F": "59",
  "humidity": "72",
  "windspeedKmph": "19",
  "windspeedMiles": "12",
  "weatherDesc": [{ "value": "Partly cloudy" }]
}

C'est la météo actuelle à Paris, sous forme de données brutes. Notez que l'API renvoie à la fois les unités métriques et impériales (temp_C et temp_F, windspeedKmph et windspeedMiles). Une application météo prend exactement ce JSON et le transforme en un bel écran avec des icônes et des couleurs. Mais les données sous-jacentes sont ce que vous regardez en ce moment.

Essayez maintenant de changer le nom de la ville dans l'URL. Remplacez paris par lyon, tokyo ou votre propre ville. Vous obtiendrez des données différentes, mais avec la même structure. C'est la beauté d'un endpoint : même modèle d'URL, entrée différente, même forme de réponse.

Ce qui vient de se passer :

  • Vous êtes le client (votre navigateur a envoyé la requête)
  • wttr.in est le serveur (il a cherché la météo et renvoyé du JSON)
  • L'URL est l'endpoint
  • Le JSON que vous voyez est la réponse

C'est un appel API. Vous venez d'en faire un.

Points clés à retenir

  • Chaque interaction API est une requête (une question) et une réponse (une réponse).
  • Le client demande, le serveur répond.
  • Les endpoints sont des URL. Chacun pointe vers une ressource spécifique.
  • Un appel API n'est pas magique. Vous venez d'en faire un en cliquant sur un lien.