1

# **Chapitre 4.1 : Les bases de l'API Fetch**
**Temps d'étude :** 45 minutes

---

#### **1. API Fetch : L'"antenne principale" du Centre de Contrôle de Mission**
Imaginez que dans votre Centre de Contrôle de Mission, vous disposiez d'une **énorme antenne radio** pour communiquer avec les engins spatiaux. Vous pouvez la régler sur la bonne fréquence, envoyer une commande et attendre une réponse.

L'**API Fetch** est une "antenne intégrée" similaire dans les navigateurs modernes. C'est une interface JavaScript standard pour effectuer des requêtes HTTP vers des serveurs. Elle permet de :

- 📡 Envoyer des "commandes" (GET, POST, PUT, DELETE) à notre API.
- 🛰️ Recevoir des "données de télémétrie" (données JSON) du serveur.
- ⚙️ Travailler de manière asynchrone, sans "bloquer" l'interface utilisateur en attendant une réponse.

> 💡 **Analogie spatiale :**

> La fonction `fetch()` est la commande "Antenne, établir la connexion !". Vous lui transmettez :

> - Les **coordonnées de la cible** (l'URL de notre API).
> - Le **type de commande** (méthode : GET, POST).
> - Le **contenu de la commande** (corps de la requête, en-têtes).

> En réponse, vous ne recevez pas les données elles-mêmes, mais une **promesse (Promise)** que les données arriveront.

---

#### **2. Asynchronisme : Communication à la vitesse de la lumière**
La communication avec un vaisseau spatial lointain prend du temps. Vous ne pouvez pas simplement arrêter tout le travail du Centre de Contrôle de Mission et attendre la réponse. Vous envoyez une commande et **continuez à travailler**, et lorsque la réponse arrive, le système vous en informe.

C'est cela l'**asynchronisme**. JavaScript ne bloque pas l'exécution du reste du code pendant qu'il attend une réponse du serveur. Pour gérer ce processus, l'API Fetch utilise les **Promesses (Promises)**.

Une **Promesse (Promise)** est un "reçu" indiquant que vous avez envoyé une requête. Elle a trois états :

- **`pending` (en attente) :** Le signal est toujours en cours de transmission.
- **`fulfilled` (réalisée) :** La réponse a été reçue avec succès !
- **`rejected` (rejetée) :** Une erreur s'est produite (par exemple, pas de connexion).

---

#### **3. Première requête : Découvrir la position de l'ISS**
Envoyons notre première requête à l'aide de `fetch`. Nous utiliserons un simple fichier HTML et des balises `<script>`.

**Étape 1 : Création de `index.html`**
Créez un fichier `index.html` dans un nouveau dossier (par exemple, `frontend_fleet_control`).
```html
<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>Centre de Contrôle de Mission - API Fetch</title>
</head>
<body>
    <h1>Statut de la communication avec l'ISS</h1>
    <div id="iss-status">En attente de données...</div>

    <script>
        // Notre code JavaScript sera ici
    </script>
</body>
</html>

Étape 2 : Écrire le code avec fetch À l'intérieur de la balise <script>, ajoutons notre première requête fetch vers l'API publique Open Notify.

// index.html -> <script>

const issApiUrl = 'http://api.open-notify.org/iss-now.json';
const statusDiv = document.getElementById('iss-status');

console.log('Envoi de la requête pour obtenir les coordonnées de l\'ISS...');

fetch(issApiUrl)
    .then(response => {
        // Le premier .then() traite la réponse HTTP elle-même
        console.log('Réponse reçue du serveur !', response);
        // Convertissons le corps de la réponse en JSON, c'est aussi une opération asynchrone
        return response.json();
    })
    .then(data => {
        // Le second .then() reçoit les données JSON déjà analysées
        console.log('Données converties en JSON avec succès !', data);
        const position = data.iss_position;
        statusDiv.innerHTML = `L'ISS se trouve actuellement ici :
                               <strong>Latitude :</strong> ${position.latitude},
                               <strong>Longitude :</strong> ${position.longitude}`;
    })
    .catch(error => {
        // .catch() sera déclenché si une erreur réseau se produit
        console.error('Erreur de communication avec l\'ISS !', error);
        statusDiv.textContent = 'Impossible de récupérer les données. Vérifiez votre connexion.';
    });

fetch(url) : Envoie une requête GET. Renvoie une promesse.
.then(callback) : S'exécute lorsque la promesse est résolue avec succès (fulfilled). Le premier .then reçoit un objet Response.
response.json() : Méthode qui lit le corps de la réponse et l'analyse comme du JSON. Elle renvoie également une promesse !
.catch(callback) : S'exécute si la promesse est rejetée (rejected), par exemple en raison d'une erreur réseau.

Étape 3 : Ouvrir dans le navigateur Ouvrez simplement le fichier index.html dans votre navigateur. Vous devriez voir "En attente de données..." se transformer en coordonnées actuelles de l'ISS. Ouvrez la console développeur (F12) pour voir les logs.

4. "Et si..." : Gestion des erreurs du serveur

Et si nous requêtions une URL inexistante ? fetch('http://api.open-notify.org/non-existent-endpoint')

L'API fetch est conçue de telle sorte que .catch() ne se déclenche qu'en cas d'erreurs réseau (pas d'internet, DNS introuvable). Cependant, les réponses avec les codes 404 ou 500 sont considérées par fetch comme une réponse reçue avec succès ! Elle contient simplement un code d'erreur.

La bonne façon de vérifier :

fetch('http://api.open-notify.org/non-existent-endpoint')
    .then(response => {
        // Vérifions la propriété .ok, qui est vraie pour les statuts 200-299
        if (!response.ok) {
            // Si la réponse n'est pas "OK", créons notre propre erreur pour passer au .catch()
            throw new Error(`Erreur HTTP ! Statut : ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Une erreur s\'est produite lors de l\'exécution de la requête :', error);
    });

response.ok : C'est votre principal indicateur de succès.
throw new Error() : Nous "échouons" manuellement la chaîne de promesses pour entrer dans le bloc .catch.

Quiz de consolidation

🚀 Résumé du chapitre :

Vous avez configuré l'"antenne principale" de votre Centre de Contrôle de Mission et appris à envoyer des requêtes et à recevoir des réponses.

📡 Vous avez maîtrisé la syntaxe de base de fetch().
🛰️ Vous avez compris ce que sont les Promesses (Promises) et comment travailler avec .then() et .catch().
⚙️ Vous avez appris à traiter correctement les réponses du serveur en vérifiant response.ok.

Communication établie ! Dans le prochain chapitre, nous connecterons notre Centre de Contrôle de Mission à l'API de la flotte spatiale que nous avons créée avec FastAPI, et nous apprendrons à récupérer et à afficher la liste de nos vaisseaux.

📌 Vérification :

Assurez-vous que votre fichier index.html affiche correctement les coordonnées de l'ISS.

Essayez de casser intentionnellement l'URL et voyez quelle erreur est affichée dans la console du développeur.

⚠️ Si le code ne fonctionne pas :

Erreur CORS : Si vous essayez de faire une requête vers votre API FastAPI locale (par exemple, http://127.0.0.1:8000) à partir d'un fichier ouvert en tant que file:///..., le navigateur bloquera la requête en raison de la politique de sécurité CORS. Nous résoudrons ce problème dans le prochain chapitre. Pour l'instant, nous utilisons des API publiques qui l'autorisent.

HTTP/HTTPS : http://api.open-notify.org fonctionne en HTTP. Certains navigateurs peuvent émettre un avertissement à ce sujet. Si vous travaillez depuis un site HTTPS, les requêtes vers des ressources HTTP peuvent être bloquées. ```