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.

Llamar a una API REST con Python y requests: ejemplos prácticos

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), PUT o PATCH (modificar) y DELETE (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. 200 y 201 significan éxito; 4xx indica un error en la petición (por ejemplo 401 no autorizado, 404 no encontrado, 429 demasiadas peticiones); 5xx indica 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 cabecera Retry-After cuá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 page o cursor) 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 Me gusta 0
No me gusta No me gusta 0
Me encanta Me encanta 0
Divertido Divertido 0
Enfadado Enfadado 0
Triste Triste 0
¡Vaya! ¡Vaya! 0