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 in gran parte degli endpoint di elenco, ad esempio GET /api/v3/purchases, GET /api/v3/domains o GET /api/v3/hostings. La specifica mostra che questi endpoint accettano normalmente i parametri di query page e per_page, entrambi opzionali, con valori predefiniti rispettivamente pari a 1 e 20. fileciteturn0file0

Come funziona la paginazione standard

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

• page: indica quale pagina richiedere;
• per_page: indica quanti elementi restituire per ogni pagina.

Se non specifichi nulla, l'API restituisce in genere la prima pagina con il numero predefinito di elementi per pagina.

Un esempio tipico è:

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

La risposta ha una struttura come questa:

{
  "error": 0,
  "message": "",
  "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 di elementi richiesto per pagina.

Questa è la forma più comune della paginazione e consente di sapere subito quante pagine esistono e quando hai raggiunto l'ultima. La specifica di GET /api/v3/purchases mostra proprio questo comportamento, con page e per_page nei parametri e total, count, pages, page, per_page dentro meta. Lo stesso schema ricorre anche in molti altri endpoint di elenco. fileciteturn4file0 fileciteturn4file2 fileciteturn5file0

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:

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.

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 risultati e, allo stesso tempo, decidere quale pagina leggere.

GET /api/v3/purchases?order_status=ACTIVE&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.

Il caso speciale: paginazione limitata con next

Alcuni endpoint particolari 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 nella specifica è GET /api/v3/domains/{domain_id}/dns/records. 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. fileciteturn5file0 fileciteturn5file1

Un esempio di risposta è il seguente:

{
  "error": 0,
  "message": "",
  "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 di elementi richiesto 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.

Esempio in PHP

<?php

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

do {
    $url = $baseUrl . '/api/v3/purchases?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);
    curl_close($ch);

    $json = json_decode($response, true);

    if (!isset($json['data'], $json['meta'])) {
        break;
    }

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

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

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.

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.
• 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 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.