Gestione della paginazione e dell’ordinamento

L’API restituisce i risultati di ricerca a pagine. Ecco come navigare in modo efficiente tra grandi insiemi di risultati.

Paginazione di base

POST /resources
{
  "query": "santi",
  "page": 1,
  "page_size": 20
}
Risposta:
{
  "total": 1523,
  "page": 1,
  "page_size": 20,
  "results": [ ... 20 elementi ... ]
}

La risposta ti dice che ci sono 1.523 risultati in totale e che stai visualizzando la pagina 1 con 20 elementi.

Calcolo del numero totale di pagine

const totalPages = Math.ceil(response.total / response.page_size);
// 1523 / 20 = 76.15 → 77 pagine

Caricare la pagina successiva

// Pagina successiva semplice
currentPage++;
// Oppure costruisci l’interfaccia di paginazione
for (let page = 1; page <= totalPages; page++) {
  // Crea il pulsante della pagina
}

Ottimizzare la dimensione della pagina

Scegli la dimensione della pagina in base al tuo caso d’uso:

Pagine piccole (10-20 elementi):

• Caricamento iniziale più veloce

• Ideali per la ricerca rivolta agli utenti

• Richiedono più richieste all’API

Pagine grandi (50-100 elementi):

• Meno richieste all’API

• Ideali per l’elaborazione in batch

• Richieste individuali più lente

• Il massimo è 100 elementi

Opzioni di ordinamento

Popolare (predefinito):

{
  "order": "popular"
}

Restituisce prima le risorse scaricate di più. È la scelta migliore per mostrare contenuti di alta qualità, già validati.

Recenti:

{
  "order": "recent"
}

Restituisce prima i caricamenti più recenti. È utile per scoprire contenuti nuovi.

Esempio di scorrimento infinito

let currentPage = 1;
const pageSize = 20;
let isLoading = false;
let hasMore = true;
async function loadMore() {
  if (isLoading || !hasMore) return;
  
  isLoading = true;
  
  const response = await fetch('https://api.cathopic.com/resources', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'preghiera',
      page: currentPage,
      page_size: pageSize,
      order: 'popular'
    })
  });
  const data = await response.json();
  
  // Aggiungi i risultati alla tua UI
  appendResults(data.results);
  
  // Verifica se ci sono altre pagine
  const totalPages = Math.ceil(data.total / pageSize);
  hasMore = currentPage < totalPages;
  
  currentPage++;
  isLoading = false;
}
// Attiva allo scroll
window.addEventListener('scroll', () => {
  if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) {
    loadMore();
  }
});

Consigli per le prestazioni

• Metti in cache i risultati localmente per evitare richieste ridondanti

• Usa dimensioni di pagina appropriate per il tuo caso d’uso

• Implementa stati di caricamento per una migliore esperienza utente

• Valuta la virtualizzazione per elenchi molto grandi

• Non caricare tutte le pagine insieme: carica su richiesta

Per maggiori dettagli, consulta la documentazione completa su api.cathopic.com/docs.