Data APIs: cómo gestionar paginación en volumen alto sin perder datos por el camino

Data APIs: cómo gestionar paginación en volumen alto sin perder datos por el camino

Hay un error que aparece siempre tarde. Tu pipeline lleva semanas funcionando. Los dashboards parecen correctos. Y entonces alguien compara los totales con otra fuente y la diferencia es del 12%. No es un bug en la lógica de negocio. Es la paginación.

Gestionar la paginación en data APIs de alto volumen es uno de esos problemas que parece resuelto desde el primer día y que, en realidad, esconde varios modos de fallo que solo se manifiestan bajo presión: reinicios, latencia variable, resultados que cambian entre páginas. No es un problema de código. Es un problema de diseño.

Este post trata exactamente eso: cómo pensar la paginación cuando el volumen es alto, el tiempo real importa y perder registros tiene consecuencias reales.

El problema real: las páginas no son estáticas

La mayoría de los tutoriales de paginación asumen un dataset congelado. En APIs de datos del universo público —menciones, señales, tendencias— ese dataset no existe. Los resultados son dinámicos: mientras recorres las páginas, el índice sigue creciendo.

Esto genera tres problemas concretos:

1. Desplazamiento de offset. Si usas offset/limit clásico y entre la página 3 y la página 4 entran 50 registros nuevos, la página 4 empieza desplazada. Algunos registros caen en el hueco. Nunca los ves.
2. Duplicados entre lotes. Si la API ordena por relevancia o score en lugar de por timestamp estable, el mismo ítem puede aparecer en dos páginas consecutivas según cómo fluctúe el índice.
3. Pérdida silenciosa en reintentos. Si un lote falla y relanzas desde el mismo offset, el dataset ya ha cambiado. Estás relanzando sobre una ventana distinta.

Nada de esto lanza una excepción. Tu código termina con 200 OK en todos los requests. El problema solo aparece cuando comparas totales.

Cursor-based pagination: el patrón que sí escala

La alternativa robusta es la paginación basada en cursores. En lugar de decirle a la API "dame los registros del 300 al 400", le dices "dame los registros posteriores al ítem con ID x o timestamp t".

El cursor es un marcador de posición estable. No depende del tamaño del dataset ni de cuántos ítems se hayan añadido desde tu última llamada. Dos ventajas inmediatas:

• Reinicios seguros. Si el proceso muere en el cursor c_4892, relanzas desde ahí y no pierdes nada ni duplicas nada.
• Consistencia ante inserciones. Los nuevos registros que entran después de tu cursor no distorsionan las páginas anteriores.

El diseño de implementación es sencillo: persiste el cursor después de procesar cada página, no antes. Si persistes antes y el procesamiento falla, habrás avanzado el marcador sobre datos que no trataste.

cursor = load_cursor_from_storage()  # None si es la primera ejecución

while True:
    params = {"limit": 500}
    if cursor:
        params["after"] = cursor

    response = api_client.get("/signals", params=params)
    data = response.json()

    if not data["items"]:
        break

    process(data["items"])           # Procesa primero
    cursor = data["next_cursor"]     # Persiste después
    save_cursor_to_storage(cursor)

Este orden importa. Invertirlo es el error más común en implementaciones que "parecen funcionar" hasta que hay un corte de red.

Ventanas temporales como capa de seguridad adicional

Cuando la API expone filtros por rango de fechas (from / to), úsalos aunque ya uses cursores. Las ventanas temporales te dan una segunda capa de aislamiento.

La lógica: divide el trabajo en franjas horarias fijas (cada hora, cada 15 minutos según el volumen esperado), y trata cada franja como una unidad idempotente. Si necesitas reprocesar, reprocesas una franja, no todo el histórico.

Esto también facilita el paralelismo. Puedes lanzar workers independientes para franjas diferentes sin que interfieran entre sí. El único requisito es que la API soporte rangos de tiempo con semántica estable —es decir, que un rango consultado dos veces devuelva el mismo conjunto de resultados para datos ya cerrados.

En APIs que mezclan tiempo de publicación con tiempo de indexación, esto puede no cumplirse para las ventanas más recientes. Conviene tratar la última franja (los últimos 5-10 minutos) como no idempotente y relanzarla siempre en el siguiente ciclo.

Qué mirar cuando evalúas una data API para volumen alto

Antes de comprometer arquitectura a una API externa, hay cinco preguntas técnicas que conviene responder con documentación en mano —no con suposiciones:

1. ¿Qué tipo de paginación expone? Offset/limit es señal de alerta para datasets dinámicos. Cursor o keyset es preferible. Si solo hay offset, necesitarás compensar en tu pipeline.

2. ¿El cursor es opaco o deducible? Un cursor opaco (token aleatorio del servidor) es más robusto que uno deducible (timestamp o ID visible). Con cursores deducibles puedes construir lógica de reinicio más fina, pero también puedes romper invariantes si los deduces mal.

3. ¿Cuál es el límite de página máximo? Un límite de 100 ítems por página en un dataset de millones implica miles de roundtrips. Calcula la latencia acumulada antes de comprometerte con un SLA de ingesta.

4. ¿Hay rate limiting por ventana o por volumen total? Algunos modelos pay-as-you-go como el de FeedScale cobran por dato procesado, no por request. Eso cambia la estrategia: en lugar de minimizar llamadas, optimizas la precisión de los filtros para no pagar por señales irrelevantes.

5. ¿La API garantiza orden estable dentro de un cursor? Si el orden puede cambiar entre páginas del mismo cursor (por reindexación, por ejemplo), tienes que deduplicar por ID antes de persistir.

El log que nadie revisa hasta que hay un problema

Una práctica que marca la diferencia en producción: registra métricas de paginación, no solo de resultado.

Esto significa:

• Número de páginas por ciclo de ingesta
• Ítems totales recibidos vs. ítems únicos persistidos (diferencia = duplicados detectados)
• Cursor al inicio y al final de cada ejecución
• Timestamp real de la última señal procesada vs. timestamp de la consulta

Con estos cuatro datos puedes detectar desplazamiento de offset, duplicados silenciosos y lags de indexación antes de que afecten a los análisis derivados.

No es instrumentación compleja. Es una tabla de auditoría con cuatro columnas. Pero sin ella, cuando el número sale mal, no tienes punto de partida para diagnosticar.

Gestionar paginación bien en volumen alto no es trabajo de un día. Es un conjunto de decisiones de diseño —tipo de cursor, orden de persistencia, ventanas temporales, instrumentación— que se toman una vez pero que definen si tu pipeline aguanta meses en producción sin sorpresas. Empezar por ahí, antes de optimizar cualquier otra cosa, ahorra tiempo de diagnóstico que nunca se ve venir.

← Volver al blog