Paginación en APIs: cómo recorrer una colección

Qué significa recibir una colección paginada

Una colección paginada entrega sus resultados en partes, en lugar de devolverlos todos juntos en una sola respuesta. Para quien integra el servicio, eso convierte una lectura aparentemente sencilla en un recorrido: hay que pedir una parte, procesarla y determinar, según las reglas del endpoint, si corresponde solicitar otra. Sensedia recomienda utilizar paginación en servicios que devuelven grandes cantidades de datos; es una recomendación de esa fuente, no una regla que describa el funcionamiento de cada API. Consulta la fuente: https://www.sensedia.com.es/post/api-buenas-practicas-de-paginacion-y-filtros.

El mecanismo concreto puede variar. La documentación del servicio podría explicar una señal de continuación, un parámetro u otra forma de indicar cómo seguir; no se debe elegir una de esas posibilidades por costumbre. Antes de programar, identifica tres elementos en el contrato aplicable: cómo comienza la lectura, qué información permite continuar y qué condición significa que terminó. Si falta alguno, aclara ese punto antes de tratar una respuesta como una colección completa.

Conviene separar dos preguntas que suelen confundirse: «¿recibí una respuesta correcta?» y «¿recorrí la colección completa?». La primera se refiere a la llamada que acabas de hacer. La segunda requiere seguir el procedimiento descrito para esa operación y alcanzar su condición de cierre.

• Confirma el comportamiento del endpoint concreto; no infieras el mecanismo a partir del nombre de la API.
• Busca tanto la señal para continuar como la condición documentada para detener el recorrido.
• Considera la recomendación de Sensedia como una recomendación, no como una garantía sobre un servicio particular.

Un procedimiento práctico, condicionado al contrato

Puedes organizar la implementación como un ciclo conceptual. Este esquema no prescribe nombres de parámetros ni una estructura de respuesta universal: reemplaza cada elemento por lo que establezca la documentación técnica del endpoint.

1. Define la operación que vas a consultar y registra su método, endpoint y los parámetros iniciales requeridos. 2. Realiza la solicitud inicial y procesa el conjunto de resultados de esa respuesta. 3. Examina la información de continuación descrita por el servicio. 4. Si esa información indica que existe una parte siguiente, prepara la solicitud siguiente exactamente como lo establece el contrato y vuelve a procesar sus resultados. 5. Detén el ciclo únicamente cuando se cumpla la condición de cierre que documenta el servicio.

En pseudocódigo, la idea es: «iniciar según el contrato; mientras el contrato indique que hay continuación, solicitar la parte siguiente usando el mecanismo documentado y procesar sus resultados; detenerse cuando la señal documentada indique el final». Es pseudocódigo deliberadamente abstracto, no una receta para una API determinada. No construyas por tu cuenta una URL, un número de página o un cursor si el contrato no explica que debas hacerlo.

Antes de implementar el ciclo, anota qué dato concreto de la respuesta se interpreta como continuación y qué valor o estado marca el final. También identifica qué se debe conservar entre una solicitud y la siguiente, si el servicio lo especifica. Esta pequeña descripción hace que el flujo sea revisable por otra persona y ayuda a encontrar errores de interpretación sin atribuir al proveedor reglas que no publicó.

• Inicio: usa los parámetros iniciales que documenta la operación.
• Continuación: utiliza solo la señal y el procedimiento descritos para ese endpoint.
• Cierre: termina al cumplirse la condición publicada; no basta con que una respuesta aislada parezca tener pocos resultados.
• Si la documentación no define algún paso, deja constancia de la duda y pide una aclaración en vez de inventar una regla.

Un ejemplo específico: New Relic REST API v2

La documentación de New Relic REST API v2 indica que, cuando los datos están paginados, la respuesta incluye un encabezado Link que informa el número de páginas y cuál se está consultando. Es un ejemplo concreto de información que un proveedor documenta para su API; no demuestra que otros servicios incluyan el mismo encabezado ni permite trasladar ese comportamiento a otro endpoint. Consulta la documentación: https://docs.newrelic.com/es/docs/apis/rest-api-v2/basic-functions/pagination-api-output/.

Al revisar esta referencia, toma nota de qué dice sobre el encabezado y compáralo con la operación que realmente vas a consumir. La información descrita identifica el total de páginas y la página consultada. No presupongas, solo por conocer ese dato, cómo debe construirse la próxima solicitud: sigue las instrucciones aplicables de la documentación de New Relic para esa operación.

El ejemplo también muestra por qué es útil diferenciar «un patrón posible» de «el contrato de mi endpoint». Si un proveedor usa otra señal o define condiciones distintas, el ciclo de tu integración debe adaptarse a ellas. El ejemplo sirve para orientar la lectura de documentación, no como plantilla universal.

• El encabezado Link descrito en la fuente corresponde a New Relic REST API v2.
• Confirma en la documentación aplicable cómo se continúa el recorrido; no derives instrucciones adicionales de un dato aislado.

Qué revisar si la lectura se interrumpe o repite registros

Imagina que el proceso se detiene después de haber recibido algunas partes, pero antes de alcanzar la condición de cierre. No marques la importación como completa solo porque ya se guardaron resultados. Registra que la ejecución quedó interrumpida y revisa, antes de retomarla, qué permite el contrato sobre la continuación. No se puede asumir que una posición o un cursor se conserve o pueda recuperarse indefinidamente.

La reanudación es una decisión de implementación, no una garantía general de la API. Si la documentación no explica cómo recuperar el avance tras una interrupción, solicita esa precisión. Si sí lo explica, implementa ese procedimiento y define cómo distinguir una ejecución terminada de una pendiente. Evita presentar el último valor que observaste como un punto de reanudación válido si el servicio no lo respalda.

Otro caso práctico es recibir registros que parecen repetidos al procesar distintas partes. No los elimines automáticamente ni supongas que el servicio garantiza que no habrá repeticiones: primero compara los identificadores disponibles y revisa el contrato y el historial de la ejecución para entender qué ocurrió. Si decides que la aplicación debe tratar identificadores repetidos de una forma determinada, documenta esa regla como una decisión propia y comprueba que no oculte datos que debían conservarse.

Estas comprobaciones ayudan a diagnosticar una ejecución, pero no garantizan por sí solas una lectura completa. La estrategia correcta depende de las reglas del endpoint y de las necesidades de la integración; la evidencia disponible no respalda una estrategia universal de reanudación o deduplicación.

• Ante una interrupción, conserva información de diagnóstico y confirma si el mecanismo documentado permite retomar el recorrido.
• Ante registros repetidos, compara identificadores y revisa cómo se obtuvieron antes de decidir si se descartan.
• No confundas una ejecución que guardó datos con una ejecución que alcanzó la señal de finalización.

Controles para revisar el resultado

Como controles generales de ingeniería, puedes registrar qué operación se ejecutó, cuándo comenzó y terminó, cuántas solicitudes formaron parte del recorrido y qué señal se interpretó como cierre. Estos datos sirven para entender qué pasó en una ejecución y para comparar una lectura con otra. No son una prueba automática de integridad, y el nivel de detalle debe ser adecuado para tu sistema.

También puedes revisar los identificadores de los elementos recibidos y comparar el resultado con un conteo comunicado por el servicio, si existe. Trata las diferencias como una señal para investigar, no como una conclusión inmediata: un conteo puede ser útil como referencia, pero no demuestra por sí solo que todos los elementos esperados estén presentes. Del mismo modo, que no encuentres identificadores repetidos no demuestra que no falten registros.

Mantén separado lo que informa el servicio de lo que calcula tu propia integración. Por ejemplo, anota si un número procede de una respuesta documentada o si es el total de elementos que tu proceso contabilizó. Así evitas presentar una medición local como si fuera una garantía del proveedor y puedes localizar mejor una diferencia.

• Registra la condición de cierre que se alcanzó y las incidencias ocurridas durante el recorrido.
• Investiga diferencias de conteo o identificadores repetidos en lugar de ocultarlos automáticamente.
• Utiliza cualquier conteo de referencia solo si el servicio lo proporciona y no lo trates como prueba completa de integridad.

Qué comprobar en una integración con Apification Cloud

Apification permite integrar Cloud y sus servicios mediante REST API, OpenAPI, webhooks, iframe y JavaScript. Estas opciones describen capacidades de integración; no especifican por sí mismas cómo pagina una operación concreta ni qué parámetros, señales de continuación o garantías ofrece.

Si automatizas la lectura de recursos, aplica el procedimiento general solo después de identificar el contrato técnico de la operación que vas a consumir. Mantén anotados el endpoint, la forma documentada de continuar y la condición de cierre. Si una de esas reglas no está disponible, la integración no debería sustituirla con una convención inventada.

Apification Cloud permite organizar archivos, servicios y proyectos en un espacio versionado y compartible. Esa capacidad no implica que un endpoint use un tipo determinado de paginación. Separa las funcionalidades de la plataforma de las reglas que debe definir la documentación del servicio consultado.

• Confirma el mecanismo de continuación y la condición de cierre en la documentación técnica correspondiente.
• No atribuyas paginación, reanudación ni garantías de integridad a Apification Cloud sin documentación que lo establezca.

Preguntas frecuentes