La paginación es recuperar una lista larga por trozos en lugar de toda de golpe. Dominan dos mecanismos, y fallan de maneras distintas.
Offset frente a cursor
| Cómo pides | Falla cuando | |
|---|---|---|
| Offset | "Sáltate 40, dame 20" | La lista cambia entre llamadas — recibes duplicados o huecos |
| Cursor | "Dame 20 después de este token" | Rara vez; el token fija tu posición |
La paginación por cursor es el mejor diseño para cualquier cosa que cambie mientras la lees, que es cualquier feed social. La paginación por offset en un feed vivo te mostrará calladamente la misma publicación dos veces y se saltará otra, sin ningún error en ninguna parte.
El límite recortado
Muchas API aceptan un parámetro limit con un máximo. Lo interesante es qué pasa cuando te lo pasas:
?limit=100 en una API cuyo máximo es 40
recortado en silencio → devuelve 40, estado 200
rechazado → devuelve 400, "limit must be 1–40"
El primero parece más amable y es peor. Quien pide 100 y recibe 40 concluye que la cuenta tiene 40 elementos. Rechazamos los límites fuera de rango con un 400 exactamente por esto — en la ruta de publicaciones de Mastodon el rango es 1–40, en la ruta de publicaciones de Bluesky es 1–100, y fuera de él recibes un error en lugar de un número que significa otra cosa que lo que pediste.
Sin paginación en absoluto
Algunas fuentes no la ofrecen. La página pública de una plataforma devuelve las publicaciones que por casualidad estuvieran en el documento — medido en tres cuentas: 4, 5 y 10. No hay cursor, no hay parámetro de límite y no hay página siguiente. Lo honesto es decirlo en la página de la ruta en lugar de insinuar que la lista está completa.
¿Página vacía o final de la lista?
Son cosas distintas y deberían poder distinguirse:
- Final de la lista — ya lo tienes todo. No vuelve ningún cursor.
- Resultado vacío — esta consulta no coincidió con nada.
- Lectura fallida — algo se rompió.
Una API que devuelve un array vacío en los tres casos te deja sin poder distinguir "terminado" de "roto". En nuestro archivo la distinción equivalente se guarda en columnas separadas: una ventana que no devolvió nada se registra de forma distinta de una ventana que dio error, porque una fuente que no devuelve nada no ha fallado.
Coste
En un modelo de precio por recurso, la paginación es el coste — cada elemento de cada página es facturable. Guardar en caché los identificadores que ya tienes, en lugar de volver a paginar para redescubrirlos, suele ser la diferencia entre un trabajo asumible y uno caro.