Paginación cursor
Las rutas/v1/... que devuelven listas usan paginación cursor-based, no page + offset. Es estable ante inserts concurrentes y eficiente sobre tablas grandes.
Shape de respuesta
Query params
Filtros adicionales (ej.
status, event_type) son específicos de cada endpoint.
Ejemplo de paginar
has_more sea false y next_cursor sea null.
Patrón de cliente
Por qué cursor y no page+offset
- Estabilidad: si insertas un evento nuevo entre la página 2 y la 3, el cursor sigue apuntando al “después del último que viste”. Un
?page=3&offset=50se desplaza y muestra duplicados o saltos. - Performance: con cursor el server hace
WHERE created_at < <cursor>(usa índice). Con offset haceOFFSET 1000(escanea y descarta). - Predictibilidad:
next_cursores siempre seguro de seguir; no hay que adivinar si pediste demasiado.
Errores
?cursor=basura→400 invalid_cursor. Reiniciar paginación desde la primera página.?limit=0o negativo →400 validation_error.?limit=99999→ se trunca silenciosamente al máximo del endpoint.
Cuándo NO usar cursor
- Para mostrar “página 5 de 47” en una UI clásica → no es posible con cursor (no hay total). Si lo necesitas, considera un endpoint específico de count, o pasa a un modelo
page+offsetcon un trade-off documentado. - Para ranking/top-N → ordena en server, devuelve N items, sin paginar.