Qué es una API
API quiere decir Application Programming Interface (Interfaz de Programación de Aplicaciones). Parece complicado, pero la idea es sencilla: es una forma estandarizada de que un programa le pida cosas a otro. Tu sitio pide «dame el pronóstico del tiempo de hoy» y otro servicio responde, sin que tu sitio tenga que saber cómo se calculó esa información.
🧠 Analogía: el menú y el mesero del restaurante
Imagina que estás en un restaurante. No entras en la cocina para cocinar. Miras el menú (la lista de lo que puedes pedir), llama al mesero (hace el pedido) y recibe el plato listo. La cocina sigue oculta.
- •El menú = la documentación de la API (lo que puedes solicitar)
- •El pedido al mesero = la solicitud (pides algo)
- •El plato que llega = la respuesta (generalmente en JSON)
- •La cocina oculta = el servidor (no necesitas saber cómo funciona)
💡 Ya usas APIs sin darte cuenta
Cuando un sitio muestra «Iniciar sesión con Google», se está comunicando con la API de Google. Cuando una app muestra un mapa, está usando la API de Google Maps. Cuando ves la cotización actualizada del dólar, hay una API detrás. Las APIs son la forma en que los servicios de Internet se comunican entre sí.
Los verbos: GET, POST, PUT, DELETE
Toda solicitud tiene un verbo que indica la intención de la solicitud. Hay cuatro principales, y cada uno corresponde a una acción cotidiana: leer, crear, actualizar y borrar. Quienes ya trabajaron con bases de datos lo conocen como CRUD (Create, Read, Update, Delete).
GET
leer
Busca información sin cambiar nada. Es el verbo más común.
Ej.: «dame la lista de usuarios».
POST
crear
Envía datos nuevos para crear algo.
Ej.: «registra este nuevo usuario».
PUT
actualizar
Modifica algo que ya existe.
Ej.: «cambia el correo electrónico de este usuario».
DELETE
borrar
Elimina algo.
Ej.: «borra este usuario».
🧠 Analogía: una libreta de contactos
Piensa en una agenda de contactos en el celular. GET y es abrir y leer un contacto. POST y es agregar un contacto nuevo. PUT y editar el teléfono de un contacto que ya existe. DELETE y es borrar el contacto. Son las cuatro cosas que haces con cualquier lista de datos.
💡 Consejo: GET no cambia nada
Una regla de oro: un GET nunca debe modificar datos. Solo lee. Si necesitas crear, actualizar o borrar algo, usa POST, PUT o DELETE. Esto evita que un simple clic en "actualizar página" cause daños en el servidor.
Probar APIs: curl, Thunder Client y Postman
Antes de escribir una línea de código en tu sitio, es bueno probar la API para ver qué responde. Tienes tres opciones: el curl (en la terminal), Thunder Client (extensión de VS Code) y Postman (aplicación). Los tres hacen lo mismo: envían una solicitud y muestran la respuesta.
curl - probar desde el terminal
curl ya viene instalado en Mac, Linux y Windows moderno. Solo tienes que escribir la URL de la API:
# Solicitud GET simple
$ curl https://api.exemplo.com/usuarios/1
# La API responde con un JSON:
{"id": 1, "nome": "Ana", "email": "ana@email.com"}
curl con POST y una respuesta clara
# Enviar datos con POST (-X define el verbo, -d envía el cuerpo)
$ curl -X POST https://api.exemplo.com/usuarios \
-H "Content-Type: application/json" \
-d '{"nome": "Bia", "email": "bia@email.com"}'
{"id": 2, "nome": "Bia", "email": "bia@email.com"}
# Hacer que el JSON sea legible pasándolo por jq
$ curl https://api.exemplo.com/usuarios/1 | jq
{
"id": 1,
"nombre": "Ana",
"email": "ana@email.com"
}
👁 Qué vas a ver en la pantalla de Thunder Client
Thunder Client es una extensión gratuita de VS Code. La pantalla tiene tres partes:
- •Arriba: un campo para elegir el verbo (GET, POST...) y pegar la URL, con un botón Send.
- •En el medio: pestañas para Headers, Body y Auth (cuando la API pide una contraseña o un token).
- •Abajo: la respuesta en JSON coloreado y el estado (ej.: 200 OK) con el tiempo que tomó.
✓ Qué HACER
- ✓Probar la API antes de ponerla en el código
- ✓Guardar las solicitudes que usas mucho
- ✓Usar
jqpara leer un JSON grande
✗ Qué NO hacer
- ✗Pegar tokens secretos en capturas públicas
- ✗Probar DELETE directamente en la API de producción
- ✗Ignorar el código de estado de la respuesta
Conectar el Frontend a la API de Supabase
Ahora vamos a salir de la terminal y hacer la misma solicitud desde dentro de tu sitio, con JavaScript. La herramienta para eso es fetch, que ya viene en el navegador. En el módulo anterior creaste una base de datos en Supabase. Esta expone una API REST automática, así que puedes consultar tus datos directamente desde el frontend.
Arma la URL y los encabezados
Supabase proporciona una URL del proyecto y una clave pública (anon key). Ambas van en la solicitud.
// Datos que muestra el panel de Supabase
const URL = "https://seu-projeto.supabase.co";
const CHAVE = "sua-chave-publica-anon";
Haz el GET con fetch
Busca todas las filas de la tabla «tarefas». El await espera a que llegue la respuesta.
const resposta = await fetch(
URL + "/rest/v1/tarefas?select=*",
{ headers: { apikey: CHAVE } }
);
Convierte la respuesta en datos
La respuesta llega como texto. El .json() convierte en un array que usas en el sitio.
const tarefas = await resposta.json();
console.log(tarefas);
[{ id: 1, titulo: "Estudiar APIs", feito: false }]
El código completo, todo junto
// Busca tareas de Supabase y las muestra en pantalla
async function carregarTarefas() {
const URL = "https://seu-projeto.supabase.co";
const CHAVE = "sua-chave-publica-anon";
const r = await fetch(URL + "/rest/v1/tarefas?select=*", {
headers: { apikey: CHAVE }
});
const tarefas = await r.json();
tarefas.forEach(t => console.log(t.titulo));
}
carregarTarefas();
⚠️ Error común
Problema: "La solicitud vuelve vacía o con un error de CORS / permisos."
Solución: En Supabase, activa las políticas RLS (Row Level Security) para permitir la lectura pública de la tabla y comprueba que la URL del proyecto y la clave anon sean correctas (sin espacios de más). La clave anon es segura para usar en el frontend; la clave service_role NUNCA debe ir al navegador.
APIs públicas útiles: clima y código postal
Hay miles de APIs públicas y gratuitas que puedes usar ahora mismo. Dos muy prácticas en Brasil: la de clima y es la de CEP (ViaCEP). Probemos las dos con fetch.
ViaCEP - dirección a partir del código postal
Pasas el código postal en la URL y recibes la dirección completa. No necesitas una clave ni registrarte. Es ideal para completar formularios de dirección.
# Prueba en la terminal con curl
$ curl https://viacep.com.br/ws/01001000/json/
{
"código postal": "01001-000",
"dirección": "Praça da Sé",
"barrio": "Se",
"localidad": "São Paulo",
"uf": "SP"
}
// Lo mismo con fetch, en el sitio
const cep = "01001000";
const r = await fetch("https://viacep.com.br/ws/" + cep + "/json/");
const end = await r.json();
console.log(end.localidade); // "Sao Paulo"
Clima - pronóstico del tiempo (Open-Meteo)
Open-Meteo es gratis y no pide una clave. Le pasas la latitud y la longitud y recibes la temperatura actual.
# Temperatura actual en São Paulo
$ curl "https://api.open-meteo.com/v1/forecast?latitude=-23.55&longitude=-46.63¤t=temperature_2m"
{
"current": { "temperature_2m": 24.3 }
}
🧠 Analogía: las API públicas son bibliotecas abiertas
Una API pública es como una biblioteca de barrio: cualquiera entra, consulta un libro y se va, sin pagar. Algunas solo piden un registro (una "credencial", que es la clave de API) para controlar cuántas consultas haces al día. ViaCEP y Open-Meteo ni siquiera exigen credencial.
💡 Consejo: dónde encontrar más APIs
Busca listas de «public APIs» en GitHub. Hay APIs de cotización de monedas, feriados, frases motivacionales, datos de películas, Pokémon y mucho más. Empieza por las que no piden clave: es la forma más rápida de practicar fetch.
Manejo de errores: status y try/catch
No todas las solicitudes tienen éxito. Se cae internet, falla el servidor, el código postal no existe. Por eso, todo código que se comunica con una API necesita manejar errores. Dos herramientas: leer el código de estado de la respuesta y envolver todo en un try/catch.
OK
Todo salió bien. Llegó la respuesta.
No encontrado
El recurso solicitado no existe.
Error del servidor
La culpa es de la API, no tuya.
Una regla sencilla: los estados que empiezan con 2 son éxitos, con 4 son errores tuyos (pediste algo mal), y con 5 son errores del servidor.
Manejo de errores con try/catch y status
async function buscarCep(cep) {
try {
const r = await fetch("https://viacep.com.br/ws/" + cep + "/json/");
// r.ok es true cuando el estado es 200-299
if (!r.ok) {
throw new Error("Servidor respondeu " + r.status);
}
const dados = await r.json();
if (dados.erro) {
alert("No se encontró el código postal. Revisa el número.");
return;
}
console.log(dados.localidade);
} catch (e) {
// Entra aquí si se cayó internet o falló el fetch
alert("No fue posible conectar. Inténtalo de nuevo.");
}
}
✓ Qué HACER
- ✓Verificar
r.okor.status - ✓Envolver el fetch en un
try/catch - ✓Mostrar un mensaje claro al usuario
✗ Qué NO hacer
- ✗Suponer que la respuesta siempre llega
- ✗Mostrar el error técnico sin procesar al usuario
- ✗Dejar la pantalla bloqueada esperando para siempre
⚠️ Error común
Problema: "El fetch no llegó al catch, pero el sitio dejó de funcionar."
Solución: O fetch solo entra en catch cuando falla la conexión. Un status 404 o 500 se considera una respuesta válida para fetch. Por eso NECESITAS comprobar r.ok manualmente, como en el ejemplo anterior. Sin eso, intentas leer un JSON que no existe y el sitio falla.
📚 Resumen del módulo
Siguiente módulo:
2.4 - Variables de entorno (guarda claves y secretos fuera del código, de forma segura)