Paginar miles de infracciones sin perder consistencia

Una consulta de flota puede devolver unas pocas infracciones o varios miles. La diferencia no es sólo de tamaño: cuando el resultado es grande, recorrerlo entero lleva minutos u horas, y en ese lapso la colección sigue cambiando. Entran actas nuevas, se corrigen montos, se retiran registros y una jurisdicción caída vuelve a responder.

El cliente termina con algo que parece el listado de multas de su flota y es un collage de momentos: cada página fue correcta cuando se emitió.

Por eso, en volúmenes grandes, la primera decisión no es el tamaño de página ni el formato del cursor, sino qué promesa de consistencia sostiene el servidor entre la primera respuesta y la última.

Tres promesas que no se cumplen juntas

Conviene nombrarlas:

• consistencia dentro de la página: los ítems de una respuesta pertenecen al mismo instante;
• consistencia del recorrido: todas las páginas pertenecen al mismo corte de la colección;
• frescura: cada página refleja el estado más reciente.

Las dos últimas se excluyen. Un recorrido consistente entrega el conjunto tal como estaba al empezar y no muestra lo que entró después. Una lectura fresca muestra novedades, pero puede repetir u omitir actas cuando el borde entre páginas se mueve.

Ninguna es incorrecta; lo incorrecto es no declarar cuál está en uso. Un inventario para conciliar deuda necesita recorrido consistente; un tablero de actividad reciente tolera frescura.

Del número de fila al enlace siguiente

Con tres páginas el desplazamiento numérico casi no molesta. Con trescientas, el recorrido dura más que el intervalo entre cambios y el número de fila describe un listado de actas que ya no es el mismo.

Avanzar por el último valor entregado, sobre un orden total, es la salida conocida, y el diseño del cursor está tratado en cursores estables. Lo que agrega el volumen es que la decisión deja de ser reversible: si el recorrido no entra en la vida útil de un corte, cambiar de estrategia a mitad de camino es empezar de nuevo.

El total no describe el final

Un total de multas calculado en la primera página no describe el conjunto en la trescientos, y publicarlo sin decir a qué corte pertenece invita a una barra de progreso que nunca cierra.

Es preferible publicar un enlace a la página siguiente y una señal explícita de continuación. RFC 8288 define enlaces tipados y su serialización en el encabezado Link, y remite los nombres de relación a un registro público en lugar de que cada API invente el suyo para “la que sigue”.

Del lado del cliente la regla es simétrica: el recorrido termina cuando el servidor deja de ofrecer página siguiente, no cuando una respuesta trae menos ítems de los esperados. Tampoco conviene dar por hecho que el tamaño de página lo fija el cliente: RFC 8977, que estandariza ordenamiento y paginado en RDAP, no le da un parámetro para eso y el tamaño que publica la respuesta es informativo. Una página corta puede ser un tope interno, no un final.

Reanudar un recorrido que se cortó

Los recorridos largos se interrumpen: se cae la red, se reinicia el proceso, vence una credencial. Empezar de nuevo es caro y, si el corte venció, tampoco devuelve lo mismo.

Conviene guardar un punto de control después de cada página —cursor, revisión y cantidad acumulada— y tratar el reintento como parte del flujo normal. RFC 9110 define validadores como ETag y solicitudes condicionales, que permiten confirmar que una página ya obtenida sigue vigente sin volver a transferirla.

Si el corte vence a mitad de camino hay dos salidas honestas: reiniciar sobre una revisión nueva, o continuar registrando que hubo un salto. Seguir en silencio vuelve el resultado no auditable.

RFC 9457 define un formato de detalle de problema para respuestas HTTP, donde el consumidor identifica el problema por la URI del campo de tipo y no por el texto legible. Cursor vencido, cursor de otra flota y parámetro de paginado inválido merecen tipos distintos; ninguno debería llegar disfrazado de lista vacía.

Cuando la paginación ya no alcanza

Si recorrer el conjunto tarda más que la vida útil de un corte, el problema dejó de ser de paginación. Conviene aceptar el pedido, exponer un recurso de estado y entregar un informe de infracciones con su corte declarado, como describimos en consultas largas. Para mover ese archivo, RFC 9110 define solicitudes por rango y respuestas parciales: se pide por tramos en vez de en una sola transferencia.

Así la consistencia se resuelve al generar el corte y no se renegocia en cada página.

Qué verificar antes de confiar en un recorrido

Revisá que la respuesta declare a qué corte pertenece; que el final sea una señal del servidor, no una inferencia del cliente; que un cursor vencido produzca un error tipado; y que la cobertura viaje con los ítems, para que una página vacía nunca se lea como “sin infracciones”.

Queda una medición que suele faltar: el tiempo de la última página, no el de la primera. Un endpoint que responde rápido con cincuenta actas puede ser impracticable en la página trescientos, y ese número decide si la integración termina.

Preguntas frecuentes

¿Alcanza con paginar para no perder ni repetir infracciones?

No por sí solo. Partir la respuesta en páginas resuelve el tamaño de cada transferencia, no la estabilidad del conjunto. Si la colección cambia mientras se recorre y el servidor no declara sobre qué corte trabaja, una fila puede aparecer dos veces o quedar afuera sin que ninguna respuesta parezca errónea.

¿Una página vacía significa que la patente no tiene infracciones?

No. Significa que no hay más ítems en el recorrido que se está leyendo. Puede haber resultados en páginas anteriores, fuentes que no respondieron o un corte que ya venció. La ausencia de infracciones es una afirmación distinta y necesita cobertura completa para sostenerse.

¿Conviene pedir la página más grande que permita el servidor?

No siempre. Una página grande reduce la cantidad de solicitudes, pero aumenta el tiempo de respuesta, la memoria del cliente y el costo de reintentar una página que falló a mitad de camino. El tamaño útil se calibra midiendo la última página del recorrido, no la primera. Y no todo contrato deja elegirlo: hay APIs donde el tamaño lo fija el servidor y sólo lo informa.

¿Sirve guardar el número de página para retomar al día siguiente?

Es frágil. Un número de página sólo tiene sentido dentro de una colección estable y de un mismo tamaño de página. Para reanudar conviene guardar el cursor y la revisión que el servidor entregó, y aceptar que si ese corte venció hay que reiniciar o declarar el salto.

Notas relacionadas