Manejo de paginación y ordenamiento - Centro de Ayuda

La API devuelve resultados de búsqueda en páginas. Aquí está cómo navegar eficientemente a través de grandes conjuntos de resultados.

Paginación básica

POST /resources
{
  "query": "santos",
  "page": 1,
  "page_size": 20
}
Respuesta:
{
  "total": 1523,
  "page": 1,
  "page_size": 20,
  "results": [ ... 20 elementos ... ]
}

La respuesta te dice que hay 1,523 resultados totales, y estás viendo la página 1 con 20 elementos.

Calcular total de páginas

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

Cargar siguiente página

// Siguiente página simple
currentPage++;
// O construir UI de paginación
for (let page = 1; page <= totalPages; page++) {
  // Crear botón de página
}

Optimizar tamaño de página

Elige el tamaño de página según tu caso de uso:

Páginas pequeñas (10-20 elementos):

Carga inicial más rápida
Bueno para búsqueda de cara al usuario
Se necesitan más peticiones API

Páginas grandes (50-100 elementos):

Menos peticiones API
Bueno para procesamiento por lotes
Peticiones individuales más lentas
El máximo es 100 elementos

Opciones de ordenamiento

Popular (por defecto):

{
  "order": "popular"
}

Devuelve recursos más descargados primero. Mejor para mostrar contenido de alta calidad y probado.

Reciente:

{
  "order": "recent"
}

Devuelve subidas más recientes primero. Bueno para descubrir contenido fresco.

Ejemplo de scroll 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: 'oración',
      page: currentPage,
      page_size: pageSize,
      order: 'popular'
    })
  });
  
  const data = await response.json();
  
  // Añadir resultados a tu UI
  appendResults(data.results);
  
  // Verificar si hay más páginas
  const totalPages = Math.ceil(data.total / pageSize);
  hasMore = currentPage < totalPages;
  
  currentPage++;
  isLoading = false;
}
// Activar en scroll
window.addEventListener('scroll', () => {
  if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) {
    loadMore();
  }
});

Consejos de rendimiento

Cachea resultados localmente para evitar peticiones redundantes
Usa tamaños de página apropiados para tu caso de uso
Implementa estados de carga para mejor UX
Considera virtualización para listas muy grandes
No obtengas todas las páginas a la vez - carga bajo demanda

Para más detalles, consulta la documentación completa en api.cathopic.com/docs.