Vai al contenuto

Integrazioni e contratti API

Paginazione delle API: cursori e letture affidabili dei dati aziendali

Dividere una risposta in pagine riduce il volume trasferito per ogni richiesta, ma non definisce da solo come leggere correttamente un insieme di dati. Tra una pagina e la successiva possono comparire nuovi record, cambiare i valori di ordinamento o essere rimossi elementi già osservati. Per un’integrazione aziendale, il problema riguarda quindi il significato della lettura completa: quale insieme si vuole ottenere e come si dimostra di averlo attraversato? Il contratto deve chiarire queste condizioni prima di scegliere parametri e formato del cursore.

Redazione tecnica SoftJob7 minuti di lettura

Distinguere navigazione interattiva ed estrazione completa

Una schermata che permette di esplorare i risultati può accettare che il contenuto cambi durante la consultazione, purché il comportamento resti comprensibile. Un’esportazione destinata a riconciliare documenti richiede invece un perimetro più preciso. Le due funzioni possono condividere alcune strutture tecniche, ma hanno criteri di correttezza diversi. La guida Microsoft alla progettazione delle API tratta la paginazione tra le scelte necessarie per rendere gestibili le collezioni. Il progetto applicativo deve aggiungere le condizioni che rendono una lettura utile al proprio processo.

Consideriamo un esempio esclusivamente illustrativo: un servizio espone richieste di consegna e un sistema esterno deve acquisirle per preparare un riepilogo. Bisogna chiarire se il destinatario voglia una fotografia riferita a un momento preciso oppure un flusso progressivo da riconciliare. Nel primo caso, un elemento modificato durante l’estrazione deve essere interpretato rispetto alla fotografia scelta. Nel secondo, serve un modo per rilevare anche aggiornamenti e rimozioni. Definire soltanto quante righe restituire per pagina lascia aperta la decisione più importante.

Stabilire un ordinamento totale e coerente

La documentazione PostgreSQL su LIMIT e OFFSET sottolinea la necessità di un ordinamento prevedibile e univoco quando si leggono porzioni del risultato. Ordinare soltanto per una data che più record condividono può lasciare indefinito il confine tra pagine. Una chiave aggiuntiva, stabile e distintiva, può completare l’ordine. Devono essere concordati anche direzione, trattamento dei valori assenti e confronto dei testi. La regola deve restare identica nelle richieste successive, altrimenti la continuazione perde il significato assegnato al punto di ripresa.

Nello scenario delle consegne, il gruppo potrebbe scegliere una coppia composta da istante di creazione e identificativo. La scelta va verificata sul modello reale: il valore di creazione è immutabile? Esistono importazioni che lo assegnano retroattivamente? Un ordinamento comodo per l’interfaccia non è necessariamente adatto a un’estrazione incrementale. I test dovrebbero includere molti record con lo stesso primo valore e controllare che il passaggio di pagina non li perda o li ripeta. Un insieme con date tutte diverse non metterebbe alla prova questo confine.

Conoscere il comportamento di offset e cursori

Una paginazione per offset salta un numero di risultati prima di restituire la porzione richiesta. PostgreSQL ricorda che le righe saltate devono comunque essere calcolate, rendendo potenzialmente costosi offset elevati. Esiste inoltre una questione logica: se l’insieme cambia prima del punto di lettura, la stessa posizione numerica può corrispondere a un record diverso. Il progetto deve valutare entrambe le dimensioni, evitando di trattare il costo e la stabilità come se fossero lo stesso problema.

Un cursore può rappresentare invece l’ultimo punto attraversato secondo l’ordinamento concordato. Nel caso illustrativo, la continuazione cerca gli elementi successivi alla coppia già letta. Questo può evitare alcuni spostamenti posizionali, ma non produce automaticamente una fotografia stabile. Se un record cambia un valore usato per ordinare o filtrare, può attraversare il confine della lettura. Il contratto deve spiegare quali campi possano cambiare e quale garanzia venga offerta. La scelta del cursore richiede quindi un modello delle modifiche ammesse, oltre a una query efficiente.

Definire la consistenza tra richieste successive

Leggere più pagine significa normalmente eseguire più richieste e più interrogazioni. La documentazione PostgreSQL sull’isolamento mostra che, con Read Committed, interrogazioni successive possono vedere stati diversi anche nella stessa transazione. La garanzia effettiva dipende dal motore e dal disegno del servizio. Non è corretto dedurre che tutte le pagine appartengano allo stesso insieme soltanto perché vengono richieste rapidamente o perché il cursore contiene una data di inizio. Quel valore deve corrispondere a un meccanismo che realizzi la proprietà dichiarata.

Per il riepilogo delle consegne, il gruppo può valutare una fotografia materializzata, un riferimento a versioni storiche o una lettura progressiva con riconciliazione. Ogni soluzione ha costi e limiti, come durata della validità, spazio richiesto e gestione delle modifiche. Un limite superiore sull’identificativo può circoscrivere alcuni nuovi inserimenti senza congelare i valori dei record esistenti. È importante esplicitare questa differenza. Se occorre ricostruire esattamente un insieme passato, la progettazione deve preservare le informazioni necessarie, evitando di promettere una proprietà che i dati correnti non consentono.

Legare la continuazione a filtri e autorizzazioni

Il cursore deve essere interpretato nel contesto della ricerca che lo ha prodotto. Filtri, ordinamento e versione del contratto possono influenzare il significato della continuazione. Se il client modifica questi elementi mantenendo lo stesso cursore, il servizio deve applicare una regola documentata, per esempio richiedere una nuova estrazione. Un token opaco può semplificare l’evoluzione interna, ma non sostituisce la validazione. Quando contiene stato controllato dal client, occorre impedire che una manipolazione autorizzi un perimetro più ampio di quello consentito.

Nel nostro esempio, due aziende potrebbero consultare collezioni separate. Una continuazione ottenuta in un ambito non deve diventare una scorciatoia per leggere l’altro. Ogni richiesta mantiene i controlli necessari, anche quando il cursore è valido. Il progetto deve inoltre definire che cosa accada dopo una revoca dei privilegi o la scadenza del token. È utile restituire un errore distinguibile e una procedura di ripartenza comprensibile, senza includere nel messaggio informazioni che rivelino dati di altri soggetti. La sicurezza accompagna tutto l’attraversamento della collezione.

Progettare la ripresa senza perdere il lavoro già acquisito

Una connessione può interrompersi dopo che il destinatario ha ricevuto una pagina ma prima che ne abbia registrato l’esito. Alla ripresa, il client deve sapere quali dati siano già stati applicati e quale continuazione possa utilizzare. È utile collegare salvataggio della pagina e avanzamento del checkpoint secondo una regola coerente. Se vengono aggiornati separatamente, un arresto nel punto sbagliato può produrre ripetizioni o omissioni. Il protocollo dovrebbe chiarire se ripetere una pagina sia ammesso e quali identificativi rendano riconoscibili gli elementi già trattati.

Per le consegne illustrative, una prova può arrestare il destinatario dopo il trasferimento ma prima del completamento della registrazione. Si osserva poi se la ripresa mantenga gli stessi esiti senza duplicare gli effetti. Vanno considerati anche cursori scaduti e pagine vuote con un eventuale segnale di continuazione: il client deve seguire il contratto, senza inventare il criterio di termine. Una risposta breve può essere l’ultima pagina oppure una condizione intermedia prevista dal servizio. Questa distinzione deve essere specificata e collaudata.

Verificare completezza, costi e limiti del contratto

Il collaudo deve introdurre modifiche mentre l’estrazione è aperta: inserimenti prima e dopo il punto di ripresa, aggiornamenti ai campi ordinati, rimozioni e variazioni dei permessi. Per ogni caso si stabilisce l’insieme atteso secondo la garanzia scelta. Il solo totale finale non basta: due errori opposti possono compensarsi. Conviene confrontare identificativi e revisioni, controllare ripetizioni e distinguere risultati mancanti da elementi legittimamente esclusi. Si misurano anche tempi e lavoro sul database quando crescono profondità della lettura e dimensione delle pagine.

Per il contesto del prodotto, la pagina dedicata alle API e ai Web Services di Gestionale sul Web costituisce il riferimento pertinente; i dettagli disponibili vanno verificati nella documentazione applicabile all’integrazione. Qui il criterio rimane progettuale: una paginazione affidabile dichiara quale insieme attraversa, come continua e come gestisce il cambiamento. Questa chiarezza permette a chi realizza il client di costruire riprese e verifiche coerenti, evitando di confondere un elenco di risposte riuscite con un trasferimento completo dei dati.

Riferimenti tecnici

Per approfondire i temi tecnici trattati:

Analisi metodologica originale. Le richieste di consegna e il riepilogo sono esempi illustrativi; non descrivono clienti, endpoint o garanzie implementate da Gestionale sul Web.

A cura della redazione tecnica SoftJob. Pubblicato il .