API y FastAPI en palabras sencillas

Una API es la forma en que los programas se comunican entre sí. Uno pide, el otro responde. Tomando como ejemplo un marketplace, veremos de qué se compone una petición, cómo leer una respuesta JSON y qué comprobar cuando Claude Code conecta una fuente de datos externa. Al final aclararemos brevemente dónde puede aparecer FastAPI.

Qué es una API en palabras sencillas

Una API (Application Programming Interface) es una interfaz de programación. Define qué operaciones están disponibles y las reglas para llamarlas. No solo las aplicaciones sueltas tienen API: también las bibliotecas, el sistema operativo y el navegador. A través de ella un programa puede pedirle a otro programa, o a una parte suya, que haga algo y obtener el resultado. Aquí hablaremos sobre todo de API de red, a las que se accede por una dirección.

Imagine un restaurante. Usted, como cliente, no entra en la cocina a explicarle al cocinero cómo preparar el plato. Le dice al mesero lo que quiere del menú, él lleva el pedido a la cocina y le trae el plato listo. La API es el mesero. El programa cliente hace su pedido a través de ella, y la cocina (otro programa) lo prepara. No necesita saber cómo funciona todo por dentro: basta con conocer el menú y entender qué se puede pedir y qué llegará como respuesta.

En el fondo, una API es un contrato: "a mí se me puede llamar de esta manera, y como respuesta devuelvo este tipo de resultado".

También hay un video corto y humorístico en inglés: "How API work". Es una ilustración de la misma idea, no una explicación del tema. Todo lo necesario está en el texto de abajo.

Petición y respuesta: el ejemplo de un marketplace

Imagine un marketplace al que un proveedor envía productos desde su propio programa. Pasar miles de artículos a mano con los botones del sitio es incómodo, así que el marketplace ofrece operaciones de API para programas. Por ejemplo, POST /products agrega un producto y GET /reports devuelve un informe.

La dirección de una operación disponible se llama endpoint. Para entender una petición se miran tanto la dirección como el método HTTP. GET /products y POST /products pueden hacer cosas distintas. GET se usa normalmente para leer, y POST para enviar datos a procesar.

Los datos se envían a menudo en formato JSON. Las llaves agrupan los campos de un objeto, las cadenas van entre comillas y una lista de objetos va entre corchetes:

{
  "name": "Lámpara de escritorio",
  "price": 15000,
  "count": 350
}

El cliente envía una petición, el servidor la procesa y devuelve una respuesta. Abajo va un esquema abreviado del intercambio, no un mensaje HTTP completo:

POST /products
{ "name": "Lámpara de escritorio", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created es el estado de la respuesta, y el JSON de debajo es el cuerpo con el resultado. En una API real, la documentación indica el endpoint, el método, los parámetros obligatorios, las cabeceras, la forma de la respuesta y los posibles errores. Es más seguro empezar con un solo objeto de prueba y no con el conjunto completo de datos.

Frontend, backend y la API entre ellos

La API no sirve solo para conectar aplicaciones distintas. Muchas veces una misma aplicación está formada por dos programas, y estos también se comunican a través de una API.

El frontend es la parte de la aplicación con la que usted trabaja en el navegador. Incluye los botones, las imágenes, los menús, los formularios y el comportamiento de la página. Su lógica suele escribirse en JavaScript. Puede hacer cálculos complejos por sí mismo y también llamar al servidor cuando necesita datos o acciones del lado del servicio.

El backend es la parte de servidor de la aplicación. Procesa pagos, guarda pedidos, comprueba el acceso, busca productos. Durante el desarrollo el servidor puede funcionar en su computadora, y después de publicarlo, en un hosting. El usuario no recibe su código fuente junto con la página. Al navegador le llegan respuestas a sus peticiones.

¿Y cómo se comunican? A través de esa misma API. El backend ofrece endpoints no solo a los proveedores externos, sino también a su propio frontend:

• usted abre la página: el frontend llama al endpoint /products/list, el backend devuelve la lista de productos y el frontend la presenta de forma atractiva;
• usted pulsa "comprar": el frontend envía los datos al endpoint /orders y el backend registra el pedido.

Es decir, a través de una API pueden comunicarse tanto aplicaciones distintas como partes de una misma aplicación. En este esquema el navegador envía la petición, el backend trabaja con los datos y devuelve el resultado. La base de datos no tiene por qué ser accesible directamente desde el navegador.

Una petición desde el navegador

Más arriba dijimos que el frontend "llama a un endpoint" del backend. Veamos cómo se ve eso en código. El navegador tiene para ello una función integrada, fetch. Envía una petición HTTP a la dirección indicada y devuelve la respuesta. El cuerpo de la respuesta suele llegar en JSON, y se convierte en un objeto con el método .json().

Tomemos un catálogo de locales, es decir, combinaciones de idioma y configuración regional. Supongamos que el backend ya sabe devolver la lista en la dirección /locales y que el frontend tiene que mostrarla. Por ejemplo, el servidor devuelve:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Cómo llega la respuesta

El fragmento de abajo se ejecuta dentro de una función asíncrona, un manejador de la página. Obtiene los datos; aquí no se muestra cómo se dibuja la tabla.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Ahora locales contiene los datos para la tabla

Comprobamos res.ok antes de leer los datos. Un error HTTP como 404 o 500 no hace por sí solo que fetch termine con una excepción. Además, puede fallar la propia petición de red o puede que el JSON no se pueda analizar. El código de la página debe capturar el error de un fragmento así y mostrar un mensaje comprensible. Son causas distintas, aunque en todos los casos el usuario se queda sin los datos. Más detalles en la guía de MDN sobre fetch.

Aquí hay un par de detalles que es fácil pasar por alto:

• por defecto fetch hace un GET, una petición para obtener datos. Las demás operaciones se indican con el método; por ejemplo, nuestro marketplace recibe un producto nuevo mediante POST;
• la dirección /locales es relativa. En una página HTTP normal apunta a la raíz del mismo origin. El origin lo definen el esquema, el host y el puerto; el servidor tiene que tener esa ruta;
• fetch y .json() no devuelven el resultado de inmediato, por eso delante se escribe await, que significa "espera la respuesta".

Si abre el HTML como archivo mediante file://, la ruta /locales no se convertirá en la dirección de su servidor HTTP. Para este ejemplo la página se abre a través del servidor que implementa la ruta. El archivo HTML por sí solo no crea esa ruta.

El frontend y la API pueden estar en origins distintos. En ese caso, para que el navegador pueda leer la respuesta, el servidor de la API tiene que permitir ese acceso mediante CORS. Es un mecanismo de acceso entre sitios, no el nombre de cualquier error de red. Tener la página y la API en el mismo origin simplifica el ejemplo, pero no es obligatorio para todas las aplicaciones. Los detalles están en la descripción de CORS en MDN.

Quién le responde al navegador

¿Quién responde a fetch("/locales")? El backend, y no tiene por qué estar hecho en Python con FastAPI. Una API es un acuerdo entre programas, no un lenguaje concreto. El mismo endpoint se puede escribir en Node.js, Go o Java. Por ejemplo, en un manejador de un servidor Node.js se puede devolver el array locales ya preparado. Abajo solo hay un fragmento del manejador, no un servidor completo:

// req y res los recibe el manejador, locales se preparó de antemano
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Desde fuera sigue siendo la misma petición HTTP GET /locales, y en la respuesta llegan el estado 200 y un JSON. Al frontend no le hace falta saber en qué está escrito el backend. Necesita la dirección, las reglas de la petición y el formato de la respuesta.

Qué tipos de API hay

Conviene dividir las API según dos criterios:

• locales y de red: por ejemplo, la API de una biblioteca se llama desde el código del programa, y a una API de red se accede a través de la red. La red también puede ser interna, sin salida a internet;
• públicas e internas: las públicas están pensadas para desarrolladores externos, las internas conectan partes de un sistema. Una API pública también puede exigir registro, pago y permisos.

Las API web suelen usar HTTP, un protocolo de peticiones y respuestas. REST, un nombre que verá en la documentación, describe un enfoque para construir API; no toda API HTTP cumple REST automáticamente. Por ahora es más útil aprender a leer el código de estado de la respuesta:

• 200: todo bien;
• 201: creado (por ejemplo, un objeto nuevo después de un POST);
• 404: no encontrado;
• 401: la petición no contiene datos de autenticación válidos;
• 429: demasiadas peticiones;
• 500: error interno del servidor.

No hace falta profundizar en esto ahora. Lo importante es captar la idea misma del intercambio de peticiones y respuestas. Por ahora, con eso basta.

Para qué necesita un servicio una clave de acceso

Muchos servicios le piden primero obtener una clave de API, una cadena vinculada a su cuenta o a su proyecto. Se envía de la forma que indique la documentación, a menudo en una cabecera de la petición. El servicio comprueba el acceso y puede llevar la cuenta de cuántas peticiones ha hecho usted. En otras integraciones aparecerá la palabra token. Su propósito es parecido, pero la forma de obtenerlo, su vigencia y sus permisos pueden ser distintos.

Sin el acceso adecuado la petición no se ejecutará; por ejemplo, el servidor puede responder 401. Superar la frecuencia de peticiones permitida suele indicarse con el código 429. El significado exacto de la respuesta y los volúmenes permitidos se consultan en la documentación de cada servicio. También hay fuentes abiertas que no necesitan clave en absoluto.

Dónde buscar una API ya hecha

Mediante API se integran en las aplicaciones mapas, el pronóstico del tiempo, pagos y envíos. La documentación abierta ayuda a entender qué ofrece un servicio antes de conectarlo. Es mejor empezar por la propia tarea. Defina qué datos necesita, con qué frecuencia deben actualizarse y qué va a hacer con ellos.

Para buscar, conviene echar un vistazo a Postman Public API Network, un catálogo de API y de ejemplos de peticiones. El ejemplo que encuentre es solo un punto de partida. La dirección, el formato, el acceso y las limitaciones hay que contrastarlos de todos modos con la documentación oficial del propietario del servicio.

Dónde entra FastAPI

FastAPI es uno de los frameworks para crear API y servidores web en Python. Puede vincular un endpoint con su código de servidor, recibir la petición y devolver una respuesta JSON. FastAPI hace falta cuando usted crea su propio backend en Python; para usar una API ya hecha no hace falta estudiarlo. En el nivel 7 basta con reconocer el nombre y entender ese límite.

Cómo funciona esto junto con Claude Code

Con estos conceptos es más fácil evaluar el trabajo del agente. Puede leer la documentación de una API ajena, escribir una petición de cliente o crear su propia API con FastAPI. Para usted lo importante es ver el camino concreto desde la petición hasta los datos en la página. ¿Quién envía la petición, quién responde y cómo se procesa la respuesta?

Por ejemplo, para un radar de terremotos existe el feed GeoJSON público del USGS. La dirección de la lista de la última hora:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Abajo hay un pequeño ejemplo didáctico de la estructura de la respuesta, con un evento inventado y un conjunto reducido de campos. No son datos actuales del USGS:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Punto de ejemplo" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

En features está el array de eventos. La ruta features[0].properties.mag lleva a la magnitud del primero. El índice 0 significa el primer elemento del array. Las coordenadas van en el orden "longitud, latitud, profundidad en kilómetros". El agente puede usar la magnitud para el tamaño del punto y las coordenadas para su posición. Si el array está vacío, no hay primer elemento; si la magnitud es null, es un valor desconocido, no un evento de fuerza cero.

Queda decidir qué mostrar después de la petición:

Mientras la petición se ejecuta, la página puede mostrar un indicador de carga. Para probar los distintos resultados conviene usar respuestas de ejemplo. Así no hay que esperar a un fallo real del servicio ni a un terremoto nuevo.

El encargo a Claude Code ahora puede sonar así:

Conecta a la página los datos de la API indicada.
Primero revisa la documentación oficial: dirección, método,
formato de la respuesta y condiciones de acceso. Muestra qué campos usas.
Prevé la carga, la lista vacía y el error de actualización.
Si usas datos antiguos después de un fallo, indícalo en la página.
No pongas la clave secreta en el código del cliente.
Comprueba el resultado e informa qué estados pudiste comprobar.

Cuando el agente termine, revise la propia petición y el resultado de la comprobación, no solo la imagen final. Distinga, además, entre el acceso del agente y el de la página. MCP puede conectar una herramienta a Claude Code, pero la aplicación publicada necesita su propia integración. Si se cierra la sesión del agente, eso no debería detener las peticiones del sitio cuando están implementadas en la propia aplicación.