Paginación

Resumen

Cuando una API devuelve una lista de recursos —usuarios, órdenes, productos—, rara vez tiene sentido devolver todos los resultados juntos. Si hay 100 000 usuarios, el cliente no quiere esperar 10 segundos ni parsear 50 MB de JSON. La paginación resuelve esto dividiendo los resultados en páginas.

Estrategias principales:

• Offset-based: ?page=3&size=20. El cliente pide la página N. Simple pero inconsistente si se insertan o eliminan items entre requests —un item puede aparecer duplicado o saltarse—.
• Cursor-based: ?cursor=abc123&size=20. El servidor devuelve un cursor —opaco, usualmente un ID o timestamp codificado— que el cliente pasa para obtener la página siguiente. Consistente incluso con inserciones y eliminaciones.
• Keyset pagination: similar a cursor-based pero el cursor es un valor de negocio —una fecha, un ID secuencial— en vez de un token opaco.

Alcance y supuestos

Este paquete cubre estrategias de paginación y su impacto en consistencia. Asume familiaridad con APIs REST.

Modelo mental

Un libro. No leés las 500 páginas de una sola vez. Leés de a una página, y el número de página es tu cursor. Si alguien arranca hojas, la numeración se desfasa. Pero si usás el contenido de la última frase como marcador —«seguí desde donde dice 'el dragón despertó'»—, los cambios en páginas anteriores no te afectan.

Uso práctico

• ✅ Cualquier endpoint que devuelva listas potencialmente grandes.
• ❌ Listas que siempre tienen menos de ~100 items y nunca crecerán.

Ejemplo trabajado: timeline de Twitter con cursor

Twitter devuelve tweets paginados con cursor: ?cursor=abc123&count=20. El cursor es opaco y el cliente lo trata como string mágico. Si entre requests aparecen 50 tweets nuevos, el cursor sigue apuntando al lugar correcto. Con paginación por offset, los tweets nuevos desplazan los resultados y el usuario ve duplicados o se salta contenido. El cursor evita eso.

Evidencia

• La paginación basada en cursores es el estándar en APIs modernas: Twitter, Stripe, Slack y GitHub la usan.