Consommer une API externe

Ce que tu vas apprendre

• Appeler une API publique que tu n'as pas écrite.
• Ne garder que les champs utiles grâce à transform.
• Relancer l'appel quand un paramètre change, et gérer l'échec.

Une API qui existe déjà

Tu n'as pas besoin d'écrire toutes tes API. Beaucoup de services en publient. Consommer une API, c'est l'appeler comme client.

TheMealDB est une API de recettes qui répond en JSON, sans clé pour la recherche testée ici. Ouvre cette adresse dans ton navigateur :

https://www.themealdb.com/api/json/v1/1/search.php?s=Arrabiata

La réponse contient une clé meals, un tableau de repas. Chacun a notamment idMeal, strMeal (le nom) et strCategory.

L'appel le plus simple

Passe l'adresse complète à useFetch, avec les paramètres dans query :

<script setup lang="ts">
const { data, status, error } = await useFetch(
  'https://www.themealdb.com/api/json/v1/1/search.php',
  { query: { s: 'Arrabiata' } }
)
</script>

<template>
  <p v-if="status === 'pending'">Chargement...</p>
  <p v-else-if="error">L'API ne répond pas.</p>
  <ul v-else>
    <li v-for="m in data?.meals" :key="m.idMeal">{{ m.strMeal }}</li>
  </ul>
</template>

query fabrique la fin de l'adresse : ?s=Arrabiata. Tu n'as pas à coller les morceaux à la main, et Nuxt encode les caractères spéciaux.

Ne garder que l'utile

Cette API renvoie des dizaines de champs par repas (strMealThumb, strInstructions, strIngredient1 à strIngredient20...). Ton site n'en veut que trois. L'option transform modifie la réponse avant qu'elle soit stockée :

type Repas = { idMeal: string, strMeal: string, strCategory: string }

const { data: recettes } = await useFetch('https://www.themealdb.com/api/json/v1/1/search.php', {
  query: { s: 'Arrabiata' },
  transform: (reponse: { meals: Repas[] | null }) =>
    (reponse.meals ?? []).map(m => ({ id: m.idMeal, titre: m.strMeal, categorie: m.strCategory }))
})

Deux avantages. Tes composants lisent recette.titre, pas strMeal : si l'API change, tu corriges un seul endroit. Et moins de données sont envoyées du serveur au navigateur.

Relancer quand un paramètre change

Pour une recherche, le texte tapé change. Mets-le dans un ref et dis à useFetch de surveiller :

<script setup lang="ts">
const terme = ref('Arrabiata')

const { data } = await useFetch('https://www.themealdb.com/api/json/v1/1/search.php', {
  query: { s: terme }
})
</script>

<template>
  <input v-model="terme" placeholder="Rechercher une recette" />
</template>

Passer le ref dans query suffit : useFetch relance la requête à chaque modification. C'est le même principe que la fonction passée en adresse, vue dans le cours Nuxt.

Quand l'API échoue

Une API externe n'est pas sous ton contrôle. Elle peut être lente, tomber, ou changer de format. Prévois toujours trois états : chargement, erreur, résultat vide. Dans le code plus haut, status et error les couvrent.

Pour une action déclenchée par un clic, utilise $fetch avec un try/catch :

async function rechercher() {
  try {
    resultat.value = await $fetch('https://www.themealdb.com/api/json/v1/1/search.php', {
      query: { s: terme.value }
    })
  } catch {
    message.value = 'Recherche impossible pour le moment.'
  }
}

À retenir

• Consommer une API, c'est l'appeler comme client avec useFetch (page) ou $fetch (clic).
• query construit les paramètres d'adresse ; un ref dans query relance l'appel quand il change.
• transform ne garde que les champs utiles et isole ton site du format de l'API.
• Prévois le chargement, l'erreur et le résultat vide : une API externe peut échouer.
• Une clé d'API ne se met jamais dans le code du navigateur.