Comprendre les API

Ce que tu vas apprendre

• Ce qu'est une API et pourquoi un site en a besoin.
• À quoi ressemblent une requête et une réponse HTTP.
• Lire du JSON et observer un échange réel dans les outils du navigateur.

Une API, c'est un guichet

Une API (interface de programmation) est un ensemble d'adresses auxquelles un programme peut poser des questions et obtenir des réponses. Le programme qui demande s'appelle le client, celui qui répond le serveur.

Ton site de recettes en a besoin : la page /recettes ne contient pas les recettes, elle les demande à une API. Tu as déjà fait ce geste avec useFetch dans le cours Récupérer des données. Ici, on regarde ce qui voyage vraiment.

Une requête et une réponse

Le langage de cet échange s'appelle HTTP. Le client envoie une requête, le serveur renvoie une réponse. Voici une requête, telle qu'elle part :

GET /api/recettes/2 HTTP/1.1
Host: monsite.fr
Accept: application/json

Et la réponse du serveur :

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 2, "titre": "Ratatouille", "duree": 60 }

Un message HTTP a toujours la même forme, d'après MDN :

1. une ligne de départ (la méthode et l'adresse pour une requête, le code de statut pour une réponse) ;
2. des en-têtes, des lignes Nom: valeur qui décrivent le message ;
3. une ligne vide ;
4. un corps, facultatif, qui contient les données.

Le JSON, le format des données

Le corps de la réponse est écrit en JSON (JavaScript Object Notation), un format texte pour décrire des données. Il ressemble à un objet JavaScript, avec des règles plus strictes.

{
  "id": 2,
  "titre": "Ratatouille",
  "duree": 60,
  "vegetarien": true,
  "ingredients": ["aubergine", "courgette", "tomate"]
}

Les règles à retenir :

• les noms de clés sont entre guillemets doubles ;
• les textes aussi (pas de guillemets simples) ;
• les valeurs possibles sont : texte, nombre, true / false, null, tableau [], objet {} ;
• pas de virgule après le dernier élément.

En JavaScript, JSON.parse(texte) transforme du JSON en objet, et JSON.stringify(objet) fait l'inverse. Nuxt le fait pour toi avec useFetch.

Observer un échange réel

Le meilleur moyen de comprendre est de regarder. Lance ton site avec npm run dev, puis :

1. ouvre http://localhost:3000/recettes ;
2. ouvre les outils du navigateur (touche F12), onglet Réseau ;
3. recharge la page et clique sur la ligne recettes qui apparaît ;
4. lis les onglets En-têtes (la requête et la réponse) et Réponse (le JSON).

Tu peux aussi appeler une API sans page du tout. Dans un terminal :

curl http://localhost:3000/api/recettes

curl envoie la requête et affiche le corps de la réponse.

Où se passe l'échange ?

Selon le moment, le client n'est pas le même. Au premier chargement, c'est le serveur Nuxt qui appelle l'API. Après un clic sur un lien, c'est le navigateur.

À retenir

• Une API est un ensemble d'adresses qu'un programme interroge ; le client demande, le serveur répond.
• HTTP échange des messages : ligne de départ, en-têtes, ligne vide, corps.
• Le JSON décrit les données : clés et textes entre guillemets doubles, pas de virgule finale.
• L'onglet Réseau des outils du navigateur et curl permettent de voir un échange réel.
• Le détail des méthodes et des codes de statut vient au chapitre suivant.