Paginazione

Tutte le chiamate API che restituiscono elenchi di risorse (pazienti, appuntamenti, fatture, referti, ecc.) sono paginate: il server non restituisce mai l'intero archivio in una sola risposta, ma una finestra di risultati che puoi scorrere richiesta per richiesta.

Struttura della risposta

Ogni endpoint di lista include nella risposta un oggetto con i seguenti campi di paginazione:

GET/v2/tenants/:tenantId/patients

Header	Value
Authorization	Bearer {access_token}
Accept	application/json

200 OK

totalCount

Il numero totale di record che soddisfano i filtri della richiesta, indipendentemente dalla finestra corrente.

Usalo per calcolare il numero di pagine, mostrare all'utente "1842 pazienti trovati", oppure decidere se vale la pena iterare ulteriori pagine.

totalCount = 1842   →   pagine totali con limit=50: ceil(1842/50) = 37

offset

La posizione di partenza (zero-based) della finestra corrente all'interno dell'elenco totale.

• offset: 0 → stai leggendo dal primo record
• offset: 50 → stai leggendo dal cinquantunesimo record
• offset: 100 → stai leggendo dal centunesimo record

offset rispecchia il valore che hai inviato nella query string. Se non lo invii, il default è 0.

limit

Il numero massimo di record restituiti in questa risposta.

Il valore effettivo nella risposta può essere inferiore al limit richiesto se sei sull'ultima pagina e i record rimanenti sono meno del limite. limit rispecchia il valore che hai inviato (o il default del server se non lo hai specificato).

totalCount=1842, offset=1800, limit=50  →  items contiene 42 record (gli ultimi)

hasMore

Flag booleano che indica se esistono ulteriori record dopo la finestra corrente.

Valore	Significato
true	Ci sono altri record — incrementa offset e fai un'altra richiesta
false	Hai raggiunto la fine dell'elenco — non servono altre richieste

hasMore è la condizione di uscita ideale per i cicli di paginazione: smetti di fare richieste quando diventa false, senza dover calcolare manualmente l'aritmetica tra totalCount e offset.

Parametri di query string

Puoi controllare la finestra di risultati passando offset e limit nella query string di ogni richiesta di lista.

Parametro	Tipo	Default	Descrizione
offset	intero ≥ 0	0	Indice del primo record da restituire
limit	intero > 0	dipende dall'endpoint	Numero massimo di record da restituire

Esempio

Di seguito sono illustrate le chiamate in sequenza.

GET/v2/tenants/:tenantId/patients

Header	Value
Authorization	Bearer {access_token}
Accept	application/json

200 OK

Consigli pratici

Scegli un limit adeguato al tuo caso d'uso. Per sincronizzazioni in background puoi usare valori alti (es. 200–500) per ridurre il numero di richieste. Per interfacce utente, valori più bassi (20–50) rendono la navigazione più reattiva.

Non saltare pagine basandoti su totalCount da soli. Il totalCount può cambiare tra una richiesta e l'altra se i dati vengono modificati in concorrenza. Usa sempre hasMore come condizione di uscita.

Combinare paginazione e filtri. I parametri offset e limit si combinano con qualsiasi altro filtro supportato dall'endpoint (date, stato, ecc.): totalCount rifletterà sempre il numero di record che soddisfano i filtri attivi.

Prossimi passi

• Rate limiting — limiti al numero di richieste per finestra temporale
• Riferimento API — endpoint disponibili e struttura delle risorse
• Swagger — documentazione interattiva con tutti i parametri