Gerenciando paginação e ordenação

A API retorna resultados de pesquisa em páginas. Veja como navegar de forma eficiente por grandes conjuntos de resultados.

Paginação básica

POST /resources
{
  "query": "saints",
  "page": 1,
  "page_size": 20
}
Resposta:
{
  "total": 1523,
  "page": 1,
  "page_size": 20,
  "results": [ ... 20 itens ... ]
}

A resposta informa que há 1.523 resultados no total e que você está visualizando a página 1 com 20 itens.

Calculando o total de páginas

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

Carregando a próxima página

// Próxima página simples
currentPage++;
// Ou crie a interface de paginação
for (let page = 1; page <= totalPages; page++) {
  // Crie o botão da página
}

Otimizando o tamanho da página

Escolha o tamanho da página com base no seu caso de uso:

Páginas pequenas (10-20 itens):

• Carregamento inicial mais rápido

• Bom para pesquisa voltada ao usuário

• Mais solicitações à API

Páginas grandes (50-100 itens):

• Menos solicitações à API

• Bom para processamento em lote

• Solicitações individuais mais lentas

• O máximo é 100 itens

Opções de ordenação

Popular (padrão):

{
  "order": "popular"
}

Retorna primeiro os recursos mais baixados. Melhor para exibir conteúdo de alta qualidade e comprovado.

Recente:

{
  "order": "recent"
}

Retorna primeiro os uploads mais novos. Bom para descobrir conteúdo recente.

Exemplo de rolagem infinita

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: 'prayer',
      page: currentPage,
      page_size: pageSize,
      order: 'popular'
    })
  });
  
  const data = await response.json();
  
  // Adicione os resultados à sua interface
  appendResults(data.results);
  
  // Verifique se há mais páginas
  const totalPages = Math.ceil(data.total / pageSize);
  hasMore = currentPage < totalPages;
  
  currentPage++;
  isLoading = false;
}
// Acione ao rolar
window.addEventListener('scroll', () => {
  if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) {
    loadMore();
  }
});

Dicas de desempenho

• Armazene em cache os resultados localmente para evitar solicitações redundantes

• Use tamanhos de página adequados ao seu caso de uso

• Implemente estados de carregamento para uma melhor experiência do usuário

• Considere virtualização para listas muito grandes

• Não busque todas as páginas de uma vez — carregue sob demanda

Para mais detalhes, consulte a documentação completa em api.cathopic.com/docs.