Capítulo 4.1: Fundamentos de la API Fetch

Tiempo de estudio: 45 minutos

1. API Fetch: La "Antena Principal" del Centro de Control de Misiones

Imagina que en tu Centro de Control de Misiones tienes una enorme antena de radio para comunicarte con las naves espaciales. Puedes ajustarla a la frecuencia correcta, enviar un comando y esperar una respuesta.

La API Fetch es una "antena incorporada" similar en los navegadores modernos. Es una interfaz estándar de JavaScript para realizar solicitudes HTTP a los servidores. Permite:

📡 Enviar "comandos" (GET, POST, PUT, DELETE) a nuestra API.
🛰️ Recibir "telemetría" (datos JSON) del servidor.
⚙️ Trabajar de forma asíncrona, sin "congelar" la interfaz de usuario mientras se espera una respuesta.

💡 Analogía espacial:

fetch() es el comando "¡Antena, establecer comunicación!". Le pasas:

Coordenadas del objetivo (URL de nuestra API).

Tipo de comando (método: GET, POST).

Contenido del comando (cuerpo de la solicitud, cabeceras).

En respuesta, no recibes los datos directamente, sino una promesa (Promise) de que los datos llegarán.

2. Asincronía: Comunicación a velocidades de la luz

La comunicación con una nave espacial lejana lleva tiempo. No puedes simplemente detener todo el trabajo del Centro de Control de Misiones y esperar a que llegue una respuesta. Envías un comando y continúas trabajando, y cuando la respuesta llega, el sistema te notifica.

Esto es la asincronía. JavaScript no bloquea la ejecución del resto del código mientras espera una respuesta del servidor. Para gestionar este proceso, la API Fetch utiliza Promesas (Promises).

Una Promesa (Promise) es un "recibo" de que has enviado una solicitud. Tiene tres estados:

pending (pendiente): La señal aún está en camino.
fulfilled (cumplida): ¡Respuesta recibida con éxito!
rejected (rechazada): Ocurrió un error (por ejemplo, sin conexión).

3. Primera solicitud: Averiguar dónde está la ISS

Vamos a enviar nuestra primera solicitud usando fetch. Utilizaremos un simple archivo HTML y etiquetas <script>.

Paso 1: Crear index.html Crea un archivo index.html en una nueva carpeta (por ejemplo, frontend_fleet_control).

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>Centro de Control de Misiones - Fetch API</title>
</head>
<body>
    <h1>Estado de la comunicación con la ISS</h1>
    <div id="iss-status">Esperando datos...</div>

    <script>
        // Nuestro código JavaScript irá aquí
    </script>
</body>
</html>

Paso 2: Escribir código con fetch Dentro de la etiqueta <script>, añadiremos nuestra primera solicitud fetch a la API pública de Open Notify.

// index.html -> <script>

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

console.log('Enviando solicitud para obtener las coordenadas de la ISS...');

fetch(issApiUrl)
    .then(response => {
        // El primer .then() maneja la propia respuesta HTTP
        console.log('¡Respuesta recibida del servidor!', response);
        // Convertimos el cuerpo de la respuesta a JSON, esto también es una operación asíncrona
        return response.json();
    })
    .then(data => {
        // El segundo .then() recibe los datos JSON ya parseados
        console.log('¡Datos convertidos a JSON con éxito!', data);
        const position = data.iss_position;
        statusDiv.innerHTML = `La ISS se encuentra actualmente aquí:
                               <strong>Latitud:</strong> ${position.latitude},
                               <strong>Longitud:</strong> ${position.longitude}`;
    })
    .catch(error => {
        // .catch() se activará si ocurre un error de red
        console.error('¡Error de comunicación con la ISS!', error);
        statusDiv.textContent = 'No se pudieron obtener los datos. Comprueba tu conexión.';
    });

fetch(url): Envía una solicitud GET. Devuelve una promesa.
.then(callback): Se ejecuta cuando la promesa se resuelve (fulfilled) con éxito. El primer .then recibe un objeto Response.
response.json(): Método que lee el cuerpo de la respuesta y lo parsea como JSON. ¡También devuelve una promesa!
.catch(callback): Se ejecuta si la promesa es rechazada (rejected), por ejemplo, debido a un error de red.

Paso 3: Abrir en el navegador Simplemente abre el archivo index.html en tu navegador. Deberías ver cómo "Esperando datos..." cambia a las coordenadas actuales de la ISS. Abre la consola del desarrollador (F12) para ver los logs.

4. "¿Qué pasa si...": Manejo de errores del servidor

¿Qué pasa si solicitamos una URL inexistente? fetch('http://api.open-notify.org/non-existent-endpoint')

Fetch está diseñado de tal manera que .catch() solo se activará en caso de errores de red (sin internet, DNS no encontrado). Sin embargo, las respuestas con códigos 404 o 500 para fetch son una respuesta recibida con éxito! Simplemente contiene un código de error.

La forma correcta de verificar:

fetch('http://api.open-notify.org/non-existent-endpoint')
    .then(response => {
        // Verificamos la propiedad .ok, que es true para estados 200-299
        if (!response.ok) {
            // Si la respuesta no es "OK", creamos nuestro propio error para pasar a .catch()
            throw new Error(`¡Error HTTP! Estado: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Ocurrió un error al ejecutar la solicitud:', error);
    });

response.ok: Este es tu principal indicador de éxito.
throw new Error(): Fallamos manualmente la cadena de promesas para entrar en el bloque .catch.

Cuestionario de repaso

🚀 Resumen del capítulo:

Ha configurado la "antena principal" de su MCC y ha aprendido a enviar solicitudes y recibir respuestas.

📡 Ha dominado la sintaxis básica de fetch().
🛰️ Ha entendido qué son las Promesas (Promises) y cómo trabajar con .then() y .catch().
⚙️ Ha aprendido a procesar correctamente las respuestas del servidor, verificando response.ok.

¡Conexión establecida! En el próximo capítulo, conectaremos nuestro MCC a la API de la flota espacial que hemos creado con FastAPI, y aprenderemos a obtener y mostrar la lista de nuestras naves.

📌 Verificación:

Asegúrese de que su archivo index.html muestre correctamente las coordenadas de la ISS.

Intente romper intencionalmente la URL y observe en la consola del desarrollador qué error se muestra.

⚠️ Si el código no funciona:

Error CORS: Si intenta hacer una solicitud a su API local de FastAPI (por ejemplo, http://127.0.0.1:8000) desde un archivo abierto como file:///..., el navegador bloqueará la solicitud debido a la política de seguridad CORS. Resolveremos este problema en el próximo capítulo. Por ahora, estamos usando APIs públicas que lo permiten.

HTTP/HTTPS: http://api.open-notify.org funciona con HTTP. Algunos navegadores pueden advertirlo. Si está trabajando desde un sitio HTTPS, las solicitudes a recursos HTTP pueden ser bloqueadas.