Guida all'uso del Skip & Take durante l'utilizzo delle API

si spiega il concetto dei 2 valori SKIP e TAKE validi per molte delle API disponibili su TakeOff.

Written By Tony Casasola

Last updated About 2 months ago

TakeOff_API_SKIP_TAKE_Guide.docx

12.6 KB• Document

TakeOff CRM

Documentazione API

Guida alla Paginazione: Parametri SKIP e TAKE

Versione 1.0 | Uso: Integratori esterni

1. Introduzione

Le API di TakeOff CRM che restituiscono elenchi di record supportano un meccanismo di paginazione basato sui parametri SKIP e TAKE. Questo approccio consente agli integratori di recuperare i dati in blocchi gestibili, evitando risposte eccessive e garantendo performance ottimali.

Questa guida descrive come utilizzare correttamente questi parametri, con esempi pratici e indicazioni sulle best practice.

2. Concetti fondamentali

Il modello SKIP/TAKE è uno standard consolidato per la paginazione nelle API REST. Si basa su due semplici concetti:

Parametro	Tipo	Descrizione
SKIP	integer	Numero di record da saltare dall'inizio del dataset. Corrisponde all'offset della pagina. Valore minimo: 0.
TAKE	integer	Numero massimo di record da restituire nella risposta. Corrisponde alla dimensione della pagina (page size).

💡 Analogia: immagina di sfogliare un registro cartaceo. SKIP ti dice quante righe saltare prima di iniziare a leggere, TAKE ti dice quante righe leggere da quel punto in poi.

3. Come funziona la paginazione

3.1 Formula generale

Per navigare tra le pagine, si applica la seguente formula:

SKIP = (numeroPagina - 1) × TAKE

Pagina 1 → SKIP = 0, TAKE = 20

Pagina 2 → SKIP = 20, TAKE = 20

Pagina 3 → SKIP = 40, TAKE = 20

Pagina N → SKIP = (N-1) × 20, TAKE = 20

3.2 Esempio visivo

Supponiamo di avere 60 record totali e di voler leggere 20 record per pagina:

Pagina	SKIP	TAKE	Record restituiti
1	0	20	Record 1 – 20
2	20	20	Record 21 – 40
3	40	20	Record 41 – 60

4. Esempi di utilizzo

4.1 Prima pagina (primi 20 record)

GET https://webapi.takeoffcrm.com/api/activities?skip=0&take=20

Authorization: Bearer {token}

4.2 Seconda pagina (record 21–40)

GET https://webapi.takeoffcrm.com/api/activities?skip=20&take=20

Authorization: Bearer {token}

4.3 Prima pagina con dimensione personalizzata (50 record)

GET https://webapi.takeoffcrm.com/api/activities?skip=0&take=50

Authorization: Bearer {token}

4.4 Struttura della risposta

Le API di TakeOff che supportano la paginazione restituiscono tipicamente una struttura che include il totale dei record disponibili, utile per calcolare il numero totale di pagine:

{

"total": 243,

"items": [

{ "id": "...", ... },

...

]

}

Il campo total indica il numero complessivo di record presenti nel dataset (senza paginazione). Utilizzando questo valore insieme al TAKE scelto, è possibile calcolare il numero totale di pagine:

totalPagine = Math.ceil(total / take)

Esempio: total=243, take=20 → Math.ceil(243 / 20) = 13 pagine

5. Recupero completo del dataset

Per recuperare tutti i record disponibili è necessario iterare le chiamate incrementando SKIP fino a quando il numero di record restituiti è inferiore al TAKE richiesto, oppure quando SKIP supera il valore di total.

// Pseudocodice - recupero completo dataset

let skip = 0;

const take = 100;

let allRecords = [];

do {

const response = await fetch(`/api/activities?skip=${skip}&take=${take}`);

const data = await response.json();

allRecords = allRecords.concat(data.items);

skip += take;

} while (allRecords.length < data.total);

⚠️ Attenzione: il recupero completo di dataset molto grandi può essere oneroso. Si raccomanda di applicare filtri laddove disponibili per limitare il numero di record restituiti, e di non eseguire questo tipo di operazione con frequenza eccessiva.

6. Best practice

Raccomandazione	Motivazione
Usare un TAKE tra 20 e 100 record	Bilancia performance e numero di richieste. Valori molto alti possono causare timeout.
Non usare TAKE eccessivamente alto (es. 10.000)	Rischio di risposta lenta o errori server, specialmente su dataset grandi.
Gestire il campo total per determinare la fine dei dati	Evita chiamate inutili quando tutti i record sono già stati recuperati.
Usare SKIP=0 per la prima chiamata	Il valore 0 indica sempre l'inizio del dataset. Non utilizzare valori negativi.
Includere sempre entrambi i parametri	Alcuni endpoint potrebbero applicare valori di default non prevedibili se uno dei parametri è omesso.

7. Casi d'uso comuni

7.1 Interfaccia con tabella paginata

Quando si costruisce una UI con tabella paginata, il numero di pagina corrente e la dimensione della pagina (page size) sono impostati dall'utente. La traduzione nei parametri API è immediata:

// Parametri UI

const currentPage = 3; // pagina selezionata dall'utente

const pageSize = 25; // righe per pagina scelte dall'utente

// Traduzione in parametri API

const skip = (currentPage - 1) * pageSize; // → 50

const take = pageSize; // → 25

// Chiamata API risultante

GET /api/activities?skip=50&take=25

7.2 Sincronizzazione periodica

Per sincronizzazioni pianificate (es. ogni notte), è consigliabile recuperare i dati in blocchi e, se l'API supporta filtri per data, combinare SKIP/TAKE con un filtro sulla data di ultima modifica:

GET /api/activities?skip=0&take=100&updatedAfter=2025-01-01T00:00:00Z

7.3 Export completo

Per un export completo dei dati, iterare le pagine come descritto nella sezione 5, mantenendo traccia del totale restituito per determinare quando fermarsi.

8. Errori comuni e risoluzione

Errore / Comportamento	Causa probabile	Soluzione
items sempre vuoti dopo la prima pagina	SKIP non viene incrementato tra le chiamate	Assicurarsi che skip += take ad ogni iterazione
Record duplicati tra pagine consecutive	I dati nel backend sono cambiati durante il ciclo di recupero	Aggiungere un filtro su data o usare un identificatore stabile come cursore
Risposta lenta o timeout	Valore di TAKE troppo alto	Ridurre TAKE (es. da 1000 a 100)
Numero totale di record incoerente tra chiamate	Dataset in aggiornamento continuo	Considerare il total come indicativo e non come valore assoluto in ambienti live

9. Riepilogo rapido

SKIP → quanti record saltare (offset) | TAKE → quanti record restituire (limit)

Pagina N = skip=(N-1)×take | Ultima pagina raggiunta quando items.length < take oppure skip ≥ total

Per qualsiasi dubbio o segnalazione relativa alle API di TakeOff, contattare il team di integrazione tramite i canali ufficiali.