Gestione della paginazione

Molti endpoint delle API restituiscono liste di elementi invece di un singolo oggetto. In questi casi i risultati sono paginati: la risposta contiene solo una parte degli elementi disponibili e include, nel campo meta, le informazioni utili per capire quale pagina stai leggendo e come richiedere le successive.

Questo comportamento è comune a tutti gli endpoint di elenco, ad esempio GET /api/v3/purchases, GET /api/v3/domains o GET /api/v3/hostings. Questi endpoint accettano i parametri di query page e per_page, entrambi opzionali.

Come funziona la paginazione standard

Negli endpoint paginati standard puoi controllare la paginazione usando questi parametri query string:

Parametro	Default	Valori ammessi	Descrizione
page	1	da 1 a 1000000	Pagina da richiedere, a partire da 1
per_page	20	da 1 a 50	Numero di elementi per pagina

Se non specifichi nulla, l'API restituisce la prima pagina con 20 elementi.

Un valore fuori dall'intervallo ammesso, oppure non numerico, non viene corretto automaticamente: la risposta è 400 Bad Request con un errore di validazione (codice 1000). Ad esempio per_page=100 viene rifiutato: per leggere più elementi devi richiedere più pagine.

Un esempio tipico è:

GET /api/v3/purchases?page=1&per_page=20

La risposta ha una struttura come questa:

{
  "error": 0,
  "message": null,
  "data": [
    {}
  ],
  "meta": {
    "total": 125,
    "count": 20,
    "pages": 7,
    "page": 1,
    "per_page": 20
  }
}

In questo caso:

• total è il numero totale di elementi disponibili;
• count è il numero di elementi restituiti nella risposta corrente;
• pages è il numero totale di pagine disponibili;
• page è la pagina attualmente restituita;
• per_page è il numero massimo di elementi per pagina.

Questa è la forma più comune della paginazione e consente di sapere subito quante pagine esistono e quando hai raggiunto l'ultima.

Come richiedere altre pagine

Per passare alla pagina successiva basta incrementare il valore di page:

GET /api/v3/purchases?page=2&per_page=20

Per chiedere più o meno elementi per ciascuna risposta puoi invece modificare per_page, fino a un massimo di 50:

GET /api/v3/purchases?page=1&per_page=50

Una buona pratica è mantenere costante il valore di per_page mentre scorri le pagine, così da rendere più prevedibile la lettura dei risultati.

Come capire se hai finito

Negli endpoint standard hai diversi modi per capire se ci sono ancora risultati da leggere:

• se page è minore di pages, esistono altre pagine;
• se page è uguale a pages, stai leggendo l'ultima pagina;
• se count è 0, la pagina richiesta non contiene elementi.

Una pagina oltre l'ultima non è un errore: la risposta è 200 OK con data vuoto, count uguale a 0 e la page richiesta in meta.

In molti casi, per leggere tutti i risultati, puoi ripetere la chiamata aumentando page fino a raggiungere l'ultima pagina indicata da pages.

Paginazione e filtri

La paginazione può essere combinata con gli altri parametri di filtro previsti dall'endpoint. Ad esempio, nello stesso endpoint GET /api/v3/purchases puoi filtrare i soli acquisti sospesi e, allo stesso tempo, decidere quale pagina leggere.

GET /api/v3/purchases?suspended=true&page=1&per_page=20

È importante ricordare che i valori presenti in meta si riferiscono sempre all'insieme filtrato dei risultati, non all'intero archivio generale.

I filtri disponibili sono diversi per ogni endpoint e sono elencati nella sua pagina di riferimento.

Il caso speciale: paginazione limitata con next

Alcuni endpoint particolari, che leggono i dati da sistemi esterni, non possono restituire il numero totale di elementi o il numero totale di pagine. In questi casi l'API usa una paginazione più limitata: puoi comunque richiedere una pagina e impostare per_page, ma nella risposta non trovi total e pages.

L'esempio principale è GET /api/v3/domains/{domain_id}/dns/records, l'elenco dei record DNS di un dominio. La descrizione dell'endpoint indica esplicitamente che i risultati sono paginati, ma che non sono disponibili il numero totale di elementi e il numero totale di pagine e che è supportata solo la navigazione in avanti. Nel campo meta trovi infatti count, page, per_page e next.

Un esempio di risposta è il seguente:

{
  "error": 0,
  "message": null,
  "data": [
    {}
  ],
  "meta": {
    "count": 20,
    "page": 1,
    "per_page": 20,
    "next": true
  }
}

In questo caso:

• count è il numero di elementi presenti nella risposta corrente;
• page è la pagina attualmente restituita;
• per_page è il numero massimo di elementi per pagina;
• next indica se esiste una pagina successiva.

Se next vale true, puoi richiedere la pagina successiva. Se next vale false, significa che non ci sono altre pagine oltre a quella corrente.

Differenza tra paginazione standard e paginazione con next

La differenza principale è questa:

• nella paginazione standard conosci subito la dimensione complessiva del risultato, perché meta contiene total e pages;
• nella paginazione con next non conosci il totale complessivo, ma sai solo se puoi proseguire alla pagina successiva.

In pratica, con la paginazione standard puoi pianificare l'intera navigazione in anticipo. Con la paginazione limitata, invece, devi procedere pagina per pagina finché next non diventa false.

Strategia consigliata per leggere tutti i risultati

Endpoint standard

1. Richiedi la prima pagina.
2. Leggi meta.pages.
3. Continua a incrementare page fino all'ultima pagina.

Endpoint con next

1. Richiedi la prima pagina.
2. Controlla meta.next.
3. Se next è true, richiedi la pagina successiva.
4. Ripeti finché next non diventa false.

Se devi leggere molte pagine, ricorda il limite di 60 richieste al minuto per client: usa per_page=50 per ridurre il numero di chiamate e, se ricevi un 429, attendi i secondi indicati dall'header Retry-After prima di proseguire.

Esempio in PHP

<?php

$baseUrl = 'https://api.shellrent.com';
$accessToken = 'YOUR_ACCESS_TOKEN';
$page = 1;
$perPage = 50;
$allItems = [];

do {
    $url = $baseUrl . '/api/v3/purchases?' . http_build_query([
        'page' => $page,
        'per_page' => $perPage,
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Accept: application/json',
            'Authorization: Bearer ' . $accessToken,
        ],
    ]);

    $response = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $json = json_decode($response, true);

    if ($statusCode !== 200) {
        throw new RuntimeException('Errore API: ' . ($json['message'] ?? $statusCode));
    }

    $allItems = array_merge($allItems, $json['data']);

    $page++;
} while ($page <= $json['meta']['pages']);

Per un endpoint con paginazione limitata, come quello dei record DNS, la logica cambia leggermente: invece di confrontare page con pages, devi continuare finché meta.next è true.

Paginazione con gli SDK

Con gli SDK ufficiali, page e per_page sono normali parametri dei metodi di elenco, e meta è disponibile come oggetto tipizzato.

Con l'SDK PHP:

$page = 1;

do {
    $result = $client->purchases()->listPurchases(page: $page, per_page: 50);

    foreach ($result->getData() as $purchase) {
        // ...
    }

    $page++;
} while ($page <= $result->getMeta()->getPages());

Con l'SDK Python:

from shellrent_sdk import unwrap
from shellrent_sdk.client.api.purchases import list_purchases

page = 1

while True:
    result = unwrap(list_purchases.sync_detailed(client=client, page=page, per_page=50))

    for purchase in result.data:
        ...

    if page >= result.meta.pages:
        break

    page += 1

Gli SDK ripetono automaticamente le richieste respinte con 429, dopo l'attesa indicata da Retry-After.

Buone pratiche

• Controlla sempre il campo meta prima di assumere che esistano altre pagine.
• Non dare per scontato che tutti gli endpoint espongano total e pages.
• Non superare per_page=50: valori maggiori vengono rifiutati.
• Quando integri un endpoint nuovo, verifica sempre nella documentazione quali campi di meta sono previsti.
• Se devi elaborare tutti i risultati, usa un ciclo che tenga conto del tipo di paginazione dell'endpoint.
• Se applichi filtri, ricorda che la paginazione si riferisce sempre al risultato filtrato.

In sintesi

Nella maggior parte dei casi gli endpoint paginati seguono uno schema standard con page, per_page (al massimo 50) e un oggetto meta completo di total, count, pages, page e per_page. In alcuni casi particolari, invece, l'API può offrire solo una navigazione progressiva, con count, page, per_page e next.

Per questo motivo, quando lavori con endpoint che restituiscono liste, il modo corretto di leggere la risposta non è guardare solo data, ma anche usare sempre il contenuto di meta per capire come proseguire la navigazione.