Llamar a una API REST con Python y requests: ejemplos prácticos
Cómo usar la biblioteca requests para leer y enviar datos a una API REST en Python: peticiones GET y POST, JSON, autenticación, errores y reintentos automáticos.
Gran parte de los servicios que usamos a diario, desde la previsión del tiempo hasta los programas de gestión empresarial, ofrece sus datos a través de una API. Saber usarla desde Python permite automatizar muchísimas tareas: descargar datos, sincronizar dos servicios, publicar contenidos, generar informes.
En esta guía usamos requests, la biblioteca más extendida para este fin, con ejemplos que puedes ejecutar enseguida contra API públicas y gratuitas.
Qué es una API REST, en pocas palabras
Una API (Application Programming Interface) es una forma en que un programa puede pedir datos o acciones a otro programa. Las API REST funcionan a través de la web, con el mismo protocolo que los sitios, HTTP. Solo hay unos pocos conceptos que conocer:
- Endpoint: la dirección a la que se envía la petición, por ejemplo
https://api.example.com/clientes. - Método: el tipo de operación. Los principales son
GET(leer),POST(crear),PUToPATCH(modificar) yDELETE(eliminar). - JSON: el formato de texto con el que normalmente se intercambian los datos. En Python se convierte en un diccionario o una lista.
- Código de estado: un número que indica el resultado.
200y201significan éxito;4xxindica un error en la petición (por ejemplo401no autorizado,404no encontrado,429demasiadas peticiones);5xxindica un problema del servidor.
Instalar requests
Como siempre, conviene trabajar dentro de un entorno virtual. Con el entorno activo:
python -m pip install requests
La primera petición GET: el tiempo
Usamos Open-Meteo, un servicio meteorológico gratuito que no requiere registro. Pidamos el tiempo actual en Milán:
import requests
URL = "https://api.open-meteo.com/v1/forecast"
params = {
"latitude": 45.46,
"longitude": 9.19,
"current": "temperature_2m,wind_speed_10m",
"timezone": "auto",
}
response = requests.get(URL, params=params, timeout=10)
response.raise_for_status()
data = response.json()
current = data["current"]
print(f"Temperatura: {current['temperature_2m']} °C")
print(f"Viento: {current['wind_speed_10m']} km/h")
Veamos las líneas importantes:
params: requests añade los parámetros a la dirección en el formato correcto, gestionando también espacios y caracteres especiales. No hace falta componer la URL a mano.timeout=10: si el servidor no responde en 10 segundos, la petición se interrumpe. Sin timeout, un script puede quedarse bloqueado para siempre. Ponlo siempre.raise_for_status(): si el código de estado indica un error, lanza una excepción en lugar de continuar con datos erróneos.json(): convierte la respuesta en un diccionario de Python.
Un consejo práctico: cuando trabajes con una API nueva, imprime la respuesta completa con print(data) para ver su estructura antes de extraer los campos que te interesan.
Enviar datos con una petición POST
Para crear algo se usa el método POST. Para probar sin riesgos usamos JSONPlaceholder, un servicio de pruebas que simula una API real pero no guarda nada:
import requests
new_post = {
"title": "Prueba",
"body": "Contenido de prueba",
"userId": 1,
}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=new_post,
timeout=10,
)
response.raise_for_status()
print(response.status_code) # 201: creado
print(response.json()) # los datos recibidos, con el id asignado
El parámetro json= convierte el diccionario en JSON y establece automáticamente la cabecera Content-Type: application/json. Es distinto de data=, que envía los datos como un formulario web: si una API espera JSON, usa siempre json=.
Autenticación con un token
Las API privadas exigen identificarse. El método más común es un token (o clave de API) que se envía en las cabeceras de la petición:
import os
import requests
token = os.environ["API_TOKEN"]
headers = {
"Authorization": f"Bearer {token}",
"Accept": "application/json",
}
response = requests.get(
"https://api.example.com/v1/clientes",
headers=headers,
timeout=10,
)
Observa que el token no está escrito en el código: se lee de una variable de entorno. Es una regla de seguridad importante: si el código acaba en GitHub o se comparte, el token sigue siendo privado. Para definir la variable antes de lanzar el script:
# Windows, símbolo del sistema
set API_TOKEN=tu-token
# Windows, PowerShell
$env:API_TOKEN = "tu-token"
# Linux y macOS
export API_TOKEN="tu-token"
El formato exacto de la cabecera (Bearer, Token, una clave en una cabecera propia) depende de la API: siempre lo encontrarás en su documentación.
Gestionar los errores
En un script real la red puede no responder, el servidor puede estar en mantenimiento o el token puede caducar. Con un bloque try puedes gestionar cada caso con un mensaje claro:
import requests
try:
response = requests.get(URL, params=params, timeout=10)
response.raise_for_status()
except requests.exceptions.Timeout:
print("El servidor no respondió a tiempo.")
except requests.exceptions.HTTPError as error:
print(f"Error HTTP {error.response.status_code}: {error.response.text[:200]}")
except requests.exceptions.ConnectionError:
print("No se pudo conectar: comprueba la red o la dirección.")
else:
data = response.json()
print(data)
El bloque else solo se ejecuta si no ha habido errores. Imprimir una parte del texto de la respuesta (error.response.text) es útil, porque muchas API explican ahí el motivo del error.
Sesiones y reintentos automáticos
Si el script hace muchas peticiones al mismo servicio, conviene usar una sesión: reutiliza la conexión (y por tanto es más rápida) y permite definir una sola vez las cabeceras y comportamientos comunes. Con una sesión también puedes repetir automáticamente las peticiones que han fallado por problemas temporales:
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
retries = Retry(
total=3, # hasta 3 nuevos intentos
backoff_factor=1, # esperas crecientes entre un intento y otro
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET"], # repetir solo las lecturas
)
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retries))
session.headers.update({"User-Agent": "mi-script/1.0"})
response = session.get(URL, params=params, timeout=10)
response.raise_for_status()
¿Por qué repetir solo las peticiones GET? Porque leer dos veces no causa daños, mientras que repetir un POST podría crear dos veces el mismo elemento, por ejemplo dos pedidos idénticos.
Buenas prácticas
- Define siempre un timeout, en cada petición.
- Comprueba el código de estado con
raise_for_status()antes de usar los datos. - No escribas nunca tokens ni contraseñas en el código: usa variables de entorno.
- Respeta los límites de la API: muchas API limitan el número de peticiones. Si recibes un error
429, reduce el ritmo; algunas indican en la cabeceraRetry-Aftercuántos segundos esperar. - Gestiona la paginación: las API que devuelven listas largas las dividen en páginas. La documentación indica qué parámetro usar (por ejemplo
pageocursor) para pedir las páginas siguientes. - Lee la documentación de la API: direcciones, parámetros y formato de autenticación cambian de un servicio a otro.
¿Y httpx?
También podrías encontrarte con httpx, una biblioteca más reciente con una interfaz muy parecida a la de requests, que además admite peticiones asíncronas (es decir, muchas peticiones en paralelo). Para scripts y automatizaciones, requests sigue siendo la opción más sencilla; si algún día necesitas funciones asíncronas, el paso a httpx será natural.
Fuentes oficiales
Compartir
¿Cuál es tu reacción?
Me gusta
0
No me gusta
0
Me encanta
0
Divertido
0
Enfadado
0
Triste
0
¡Vaya!
0