Cómo paginar una API REST en Python (requests)

Cuando pides datos a una API REST, rara vez los recibes todos de una sola vez: para ahorrar recursos, la mayoría de las APIs divide los resultados en páginas. Si lees solo la primera, te quedas con datos incompletos. La buena noticia es que paginar una API REST en Python es sencillo con la biblioteca requests: basta un bucle que recorra todas las páginas y vaya uniendo los resultados. Veamos cómo, con ejemplos prácticos.

Requisitos previos

• Python 3.9 o superior instalado.
• La biblioteca requests instalada (pip install requests).
• Una API REST que devuelva datos en páginas y acceso a su documentación.
• Conocimientos básicos de Python (diccionarios y bucles while).

Paso 1: Hacer la primera petición a la API

Antes de pensar en páginas, asegúrate de que puedes obtener una. Con requests.get haces una petición y, con raise_for_status, garantizas que cualquier error de red o de autenticación se señale de inmediato en lugar de pasar desapercibido. El timeout evita que tu programa se quede colgado esperando para siempre.

import requests

BASE_URL = "https://api.example.com/items"

resposta = requests.get(BASE_URL, params={"page": 1}, timeout=10)
resposta.raise_for_status()
dados = resposta.json()
print(dados)

Sustituye BASE_URL por el endpoint real de tu API. Al imprimir la respuesta puedes ver la estructura de los datos: normalmente un diccionario con una lista de registros dentro.

Paso 2: Entender cómo pagina la API

Existen dos estilos de paginación muy comunes, y necesitas saber cuál usa tu API (su documentación te lo dice). En el primero, indicas el número de página en un parámetro como ?page=2. En el segundo, cada respuesta trae la dirección de la página siguiente en un campo, a menudo llamado next. Las APIs creadas con Django REST Framework, por ejemplo, devuelven los campos results, next y count: la estructura que usaremos en los ejemplos.

Consejo: antes de escribir el bucle, lee la documentación de la API para conocer el nombre del parámetro de página, el tamaño máximo por página y el límite de peticiones por minuto.

Paso 3: Recorrer todas las páginas por número

La idea es sencilla: empiezas en la página 1 y vas pidiendo la siguiente hasta que la API devuelva una lista vacía, señal de que ya no hay más datos. Un contador y un bucle while bastan para ello.

todos = []
pagina = 1

while True:
    resposta = requests.get(BASE_URL, params={"page": pagina}, timeout=10)
    resposta.raise_for_status()
    lote = resposta.json()["results"]
    if not lote:
        break
    todos.extend(lote)
    pagina += 1

print(f"Total de registos: {len(todos)}")

En cada vuelta del bucle pedimos una página, añadimos sus registros a la lista todos con extend y avanzamos el contador. Cuando lote llega vacío, el break termina el bucle.

Paso 4: Seguir el campo "next" (paginación por cursor)

Si tu API devuelve la dirección de la página siguiente, ni siquiera necesitas contar páginas: sigues el campo next hasta que quede vacío. Este método es aún más robusto, porque es la propia API la que te indica el paso siguiente.

todos = []
url = BASE_URL

while url:
    resposta = requests.get(url, timeout=10)
    resposta.raise_for_status()
    dados = resposta.json()
    todos.extend(dados["results"])
    url = dados.get("next")

print(f"Total de registos: {len(todos)}")

Mientras haya un next, el bucle continúa. Cuando la última página trae next a null, get devuelve None, la condición del while pasa a falsa y el bucle termina de forma natural.

Paso 5: Evitar errores y respetar la API

Recorrer muchas páginas deprisa puede hacer que la API te bloquee por exceso de peticiones (el conocido error 429 Too Many Requests). Una breve pausa entre peticiones y un límite de seguridad hacen tu código más educado y más seguro frente a bucles infinitos.

import time

todos = []
pagina = 1
MAX_PAGINAS = 500

while pagina <= MAX_PAGINAS:
    resposta = requests.get(BASE_URL, params={"page": pagina}, timeout=10)
    resposta.raise_for_status()
    lote = resposta.json()["results"]
    if not lote:
        break
    todos.extend(lote)
    pagina += 1
    time.sleep(0.2)

print(f"Total de registos: {len(todos)}")

Comprobar el resultado

¿Cómo sabes que realmente capturaste todos los registros? Muchas APIs incluyen un campo con el total, como count. Basta comparar ese número con el tamaño de tu lista:

print(len(todos))
print(dados["count"])

Si los dos valores coinciden, la paginación recorrió todo. Como alternativa, confirma que la última página devolvió menos registros que el tamaño normal de página: señal de que llegaste al final.

Conclusión

Ya sabes paginar una API REST en Python en los dos formatos más comunes —por número de página y por el campo next— y proteger tu código con pausas y límites. El siguiente paso natural es guardar los datos de todos en un DataFrame de pandas o en una base de datos para su análisis. ¿Cuál de tus APIs vas a paginar primero?