Paginazione nelle API: come scorrere una raccolta

Che cosa significa ricevere una raccolta paginata

Una raccolta paginata restituisce i risultati in più parti, invece che tutti insieme in un’unica risposta. Per chi integra il servizio, una lettura che sembra semplice diventa così un percorso: occorre richiedere una parte, elaborarla e stabilire, secondo le regole dell’endpoint, se è necessario richiederne un’altra. Sensedia consiglia di utilizzare la paginazione nei servizi che restituiscono grandi quantità di dati; si tratta di una raccomandazione di quella fonte, non di una regola che descrive il funzionamento di ogni API. Consulta la fonte: https://www.sensedia.com.es/post/api-buenas-practicas-de-paginacion-y-filtros.

Il meccanismo specifico può variare. La documentazione del servizio può descrivere un segnale di continuazione, un parametro o un altro modo per indicare come proseguire: non scegliere una di queste possibilità per abitudine. Prima di programmare, individua tre elementi nel contratto applicabile: come iniziare la lettura, quali informazioni consentono di continuare e quale condizione indica che il processo è terminato. Se manca uno di questi elementi, chiariscilo prima di considerare completa una risposta.

È utile distinguere due domande che spesso vengono confuse: «Ho ricevuto una risposta corretta?» e «Ho scorso l’intera raccolta?». La prima riguarda la chiamata appena effettuata. La seconda richiede di seguire la procedura descritta per quell’operazione e raggiungere la relativa condizione di chiusura.

• Conferma il comportamento dello specifico endpoint; non dedurre il meccanismo dal nome dell’API.
• Cerca sia il segnale per continuare sia la condizione documentata per interrompere il percorso.
• Considera la raccomandazione di Sensedia come una raccomandazione, non come una garanzia relativa a un servizio specifico.

Una procedura pratica, subordinata al contratto

Puoi organizzare l’implementazione come un ciclo concettuale. Questo schema non prescrive nomi di parametri né una struttura universale della risposta: sostituisci ogni elemento con quanto stabilito dalla documentazione tecnica dell’endpoint.

1. Definisci l’operazione da consultare e annota il metodo, l’endpoint e i parametri iniziali richiesti. 2. Esegui la richiesta iniziale ed elabora i risultati restituiti. 3. Esamina le informazioni di continuazione descritte dal servizio. 4. Se tali informazioni indicano che esiste una parte successiva, prepara la richiesta successiva esattamente come previsto dal contratto e rielaborane i risultati. 5. Interrompi il ciclo solo quando si verifica la condizione di chiusura documentata dal servizio.

In pseudocodice, l’idea è: «iniziare secondo il contratto; finché il contratto indica che è possibile continuare, richiedere la parte successiva utilizzando il meccanismo documentato ed elaborarne i risultati; fermarsi quando il segnale documentato indica la fine». È pseudocodice volutamente astratto, non una ricetta per una specifica API. Non costruire autonomamente un URL, un numero di pagina o un cursore se il contratto non specifica che devi farlo.

Prima di implementare il ciclo, annota quale dato concreto della risposta viene interpretato come segnale di continuazione e quale valore o stato indica la fine. Individua anche quali informazioni devono essere conservate tra una richiesta e l’altra, se il servizio lo specifica. Questa breve descrizione rende il flusso verificabile da un’altra persona e aiuta a individuare errori d’interpretazione senza attribuire al fornitore regole che non ha pubblicato.

• Avvio: usa i parametri iniziali documentati per l’operazione.
• Continuazione: utilizza solo il segnale e la procedura descritti per quell’endpoint.
• Chiusura: termina quando si verifica la condizione pubblicata; non basta che una singola risposta sembri contenere pochi risultati.
• Se la documentazione non definisce un passaggio, annota il dubbio e chiedi un chiarimento invece di inventare una regola.

Un esempio specifico: New Relic REST API v2

La documentazione di New Relic REST API v2 indica che, quando i dati sono paginati, la risposta include un’intestazione Link che informa sul numero di pagine e su quale pagina si sta consultando. È un esempio concreto di informazioni documentate da un fornitore per la propria API; non dimostra che altri servizi includano la stessa intestazione e non consente di applicare quel comportamento a un altro endpoint. Consulta la documentazione: https://docs.newrelic.com/es/docs/apis/rest-api-v2/basic-functions/pagination-api-output/.

Quando esamini questa risorsa, prendi nota di ciò che dice sull’intestazione e confrontalo con l’operazione che intendi effettivamente utilizzare. Le informazioni descritte indicano il numero totale di pagine e la pagina consultata. Non dare per scontato, solo perché conosci questi dati, come costruire la richiesta successiva: segui le istruzioni applicabili della documentazione di New Relic per quell’operazione.

L’esempio mostra anche perché è utile distinguere «un possibile schema» dal «contratto del mio endpoint». Se un fornitore usa un altro segnale o definisce condizioni diverse, il ciclo dell’integrazione deve adeguarsi. L’esempio serve a orientare la lettura della documentazione, non è un modello universale.

• L’intestazione Link descritta nella fonte si riferisce a New Relic REST API v2.
• Verifica nella documentazione applicabile come proseguire; non dedurre istruzioni aggiuntive da un dato isolato.

Cosa verificare se la lettura si interrompe o ripete dei record

Immagina che il processo si interrompa dopo aver ricevuto alcune parti, ma prima di raggiungere la condizione di chiusura. Non contrassegnare l’importazione come completa solo perché i risultati sono già stati salvati. Registra che l’esecuzione è stata interrotta e, prima di riprenderla, verifica cosa prevede il contratto per continuare. Non si può presumere che una posizione o un cursore vengano conservati o possano essere recuperati a tempo indeterminato.

La ripresa è una scelta d’implementazione, non una garanzia generale dell’API. Se la documentazione non spiega come recuperare l’avanzamento dopo un’interruzione, chiedi chiarimenti. Se invece lo spiega, implementa quella procedura e definisci come distinguere un’esecuzione conclusa da una ancora in sospeso. Evita di presentare l’ultimo valore osservato come un punto di ripresa valido se il servizio non lo supporta.

Un altro caso pratico è ricevere record che sembrano ripetuti durante l’elaborazione di parti diverse. Non eliminarli automaticamente e non presumere che il servizio garantisca l’assenza di duplicati: prima confronta gli identificativi disponibili e verifica il contratto e la cronologia dell’esecuzione per capire cosa è successo. Se decidi che l’applicazione deve gestire in un determinato modo gli identificativi ripetuti, documenta la regola come una scelta autonoma e verifica che non nasconda dati da conservare.

Questi controlli aiutano a diagnosticare un’esecuzione, ma da soli non garantiscono una lettura completa. La strategia corretta dipende dalle regole dell’endpoint e dalle esigenze dell’integrazione; le informazioni disponibili non supportano una strategia universale di ripresa o deduplicazione.

• In caso di interruzione, conserva le informazioni utili alla diagnosi e verifica se il meccanismo documentato consente di riprendere il percorso.
• In caso di record ripetuti, confronta gli identificativi e verifica come sono stati ottenuti prima di decidere se scartarli.
• Non confondere un’esecuzione che ha salvato dei dati con un’esecuzione che ha raggiunto il segnale di completamento.

Controlli per verificare il risultato

Come controlli generali di ingegneria, puoi registrare quale operazione è stata eseguita, quando è iniziata e terminata, quante richieste hanno fatto parte del percorso e quale segnale è stato interpretato come chiusura. Questi dati aiutano a capire cosa è successo durante un’esecuzione e a confrontare una lettura con un’altra. Non costituiscono una prova automatica di integrità e il livello di dettaglio dovrebbe essere adeguato al sistema.

Puoi anche verificare gli identificativi degli elementi ricevuti e confrontare il risultato con un conteggio comunicato dal servizio, se disponibile. Considera le differenze un motivo per indagare, non una conclusione immediata: un conteggio può essere un riferimento utile, ma da solo non dimostra che siano presenti tutti gli elementi attesi. Allo stesso modo, non trovare identificativi ripetuti non dimostra che non manchino record.

Tieni separate le informazioni comunicate dal servizio da quelle calcolate dalla tua integrazione. Per esempio, annota se un numero proviene da una risposta documentata oppure se corrisponde al totale degli elementi conteggiati dal processo. In questo modo eviti di presentare una misurazione locale come se fosse una garanzia del fornitore e puoi individuare più facilmente eventuali differenze.

• Registra quale condizione di chiusura è stata raggiunta e gli eventuali problemi verificatisi durante il percorso.
• Indaga sulle differenze nei conteggi o sugli identificativi ripetuti invece di nasconderli automaticamente.
• Usa un eventuale conteggio di riferimento solo se il servizio lo fornisce e non considerarlo una prova completa di integrità.

Cosa verificare in un’integrazione con Apification Cloud

Apification consente di integrare Cloud e i suoi servizi tramite REST API, OpenAPI, webhook, iframe e JavaScript. Queste opzioni descrivono le capacità d’integrazione; non specificano di per sé come viene paginata una determinata operazione né quali parametri, segnali di continuazione o garanzie siano disponibili.

Se automatizzi la lettura delle risorse, applica la procedura generale solo dopo aver individuato il contratto tecnico dell’operazione che intendi utilizzare. Annota l’endpoint, il metodo documentato per continuare e la condizione di chiusura. Se una di queste regole non è disponibile, l’integrazione non dovrebbe sostituirla con una convenzione inventata.

Apification Cloud consente di organizzare file, servizi e progetti in uno spazio versionato e condivisibile. Questa capacità non implica che un endpoint utilizzi un particolare tipo di paginazione. Tieni separate le funzionalità della piattaforma dalle regole che devono essere definite dalla documentazione del servizio consultato.

• Verifica il meccanismo di continuazione e la condizione di chiusura nella documentazione tecnica pertinente.
• Non attribuire ad Apification Cloud funzionalità di paginazione o ripresa, né garanzie d’integrità, senza documentazione che le confermi.

Domande frequenti