Paginación y cursores

01En una frase #sec_4400178a

Todas las listas de la API se recorren con cursor, nunca con número de página — y el cursor es opaco: su forma no es un contrato, su uso sí lo es.

02El sobre de respuesta #sec_95dbbbe4

Cualquier punto de llamada que devuelva una lista devuelve el mismo sobre: los datos por un lado, la posición por el otro.

{
  "data": [ ... ],
  "page": {
    "limit": 100,
    "nextCursor": "YzE6NDIx"
  }
}

data lleva los elementos. page.limit recuerda el tamaño efectivamente aplicado — que no siempre es el solicitado, ver más abajo. page.nextCursor lleva la posición a retomar, o null cuando no hay más nada después.

03Recorrer #sec_6f1e95f9

La primera llamada no lleva cursor. Cada una de las siguientes retoma el nextCursor de la anterior.

GET /api/v1/campaigns?limit=100
GET /api/v1/campaigns?limit=100&cursor=YzE6NDIx
GET /api/v1/campaigns?limit=100&cursor=YzE6Mzgy

El bucle se detiene en nextCursor: null, no en una página incompleta. Una página puede devolver menos elementos que el límite solicitado sin ser la última; detenerse en esta señal haría que se perdiera la continuación, silenciosamente.

04El límite #sec_f8bab3ec

Cien elementos por defecto, quinientos como máximo. Un valor fuera de los límites no es rechazado: se ajusta a los límites, y page.limit indica entonces lo que realmente se ha aplicado.

Es por eso que page.limit aparece en la respuesta: sin él, un cliente que solicita 5000 creería haber recibido todo.

05El cursor es opaco #sec_1c8cde92

El cursor es una cadena. Lo que codifica es un detalle de implementación que puede cambiar sin previo aviso, y decodificarlo para fabricar otro es la forma más segura de romper su integración en la próxima versión.

Dos reglas son suficientes: retomar el que la respuesta anterior ha dado, tal cual; nunca construir uno.

Un cursor mal formado o manipulado no es un error: se trata como una ausencia de cursor, y el recorrido vuelve al principio. Una integración que fabricara sus propios cursores giraría en círculo sobre la primera página sin que nada lo indique.

06El orden de recorrido #sec_3157b042

El orden es estable y decreciente sobre el identificador: los elementos más recientes primero. Esto es lo que hace que el recorrido sea seguro — un elemento añadido mientras paginas aparece antes de tu posición, por lo que no desplaza lo que queda por leer y no lo verás dos veces.

La contrapartida se dice francamente: un recorrido largo no ve lo que ha sucedido después de su primera llamada. Para recuperar lo reciente, reinicie un recorrido desde el principio en lugar de continuar con el antiguo.

07Reanudar más tarde #sec_98015cd3

Un cursor sigue siendo utilizable más allá de la vida del token que lo produjo: renovar el token no obliga a recomenzar el recorrido. Conserve la posición, no la sesión.

08Para recordar #sec_35ad77bf

Un único sobre para todas las listas. Un límite entre 1 y 500, reducido en los límites y recordado en la respuesta. Un cursor que se reanuda y que nunca se fabrica. Y una única condición de parada: nextCursor a null.