Pular para o conteúdo
Criação de Apps

Paginação em APIs: como devolver listas grandes sem travar o app

Resposta rápida

Paginação é dividir uma lista grande em partes menores, entregues a cada requisição. As formas mais comuns são por página (offset e limit) e por cursor. A por página é simples, mas pode ficar lenta e inconsistente em listas grandes; a por cursor é mais estável para dados que mudam.

Neste artigo
  1. Paginação por página (offset e limit)
  2. Paginação por cursor
  3. Boas práticas
  4. Como escolher

Uma tela de pedidos que carrega rápido com 50 registros pode levar segundos com 50 mil. Se a API devolve tudo de uma vez, o servidor, a rede e o aparelho do usuário sofrem. A paginação resolve isso entregando a lista em pedaços.

Paginação por página (offset e limit)

É a forma mais conhecida. O cliente pede uma página e o tamanho dela, por exemplo página 3 com 20 itens. O servidor pula os itens anteriores e devolve os seguintes.

Vantagens:

  • Fácil de entender e implementar.
  • Permite pular direto para uma página específica.
  • Permite mostrar o total de páginas, se você contar os registros.

Limitações:

  • Em tabelas grandes, pular muitos registros fica lento, porque o banco ainda precisa percorrê-los.
  • Se itens são inseridos ou removidos entre um pedido e outro, o usuário pode ver itens repetidos ou perder alguns.

Paginação por cursor

Em vez de um número de página, o servidor devolve um cursor, um marcador que aponta para o último item recebido. O pedido seguinte diz: me dê os itens depois deste.

Vantagens:

  • Desempenho estável, mesmo em listas enormes, se houver índice na coluna de ordenação.
  • Menos inconsistência quando os dados mudam durante a navegação.
  • Boa para rolagem infinita, como em feeds.

Limitações:

  • Não permite pular para a página 50 diretamente.
  • É um pouco mais trabalhosa de implementar.
  • A ordenação precisa ser estável, por exemplo por data de criação mais identificador, para desempatar itens iguais.

Boas práticas

  1. Defina um tamanho padrão e um máximo. Não deixe o cliente pedir 100 mil itens.
  2. Garanta uma ordenação determinística. Sem ordem definida, a mesma consulta pode devolver resultados em sequências diferentes.
  3. Crie índices nas colunas de ordenação e filtro.
  4. Devolva, na resposta, informações para continuar: o cursor ou o número da próxima página, e se há mais itens.
  5. Documente os parâmetros e os limites para quem consome a API.
  6. Combine com limites de requisição. Veja rate limit: o que é e como lidar.

Como escolher

Para painéis administrativos com poucos milhares de registros e necessidade de pular páginas, a paginação por página costuma bastar. Para feeds, históricos e tabelas que crescem sem parar, prefira cursor. O importante é decidir cedo, porque mudar o formato depois quebra quem já usa a API.

Teste com volumes realistas de dados antes de lançar. Uma lista que funciona bem com dados de teste pode se comportar mal com a base de produção.

  • API
  • Backend
  • Desempenho
  • Paginação

Perguntas frequentes

Qual tamanho de página usar?

Depende do conteúdo e da tela. Defina um padrão razoável, como algumas dezenas de itens, e imponha um máximo para evitar abuso.

Posso paginar sem mudar o banco de dados?

Sim, mas a consulta precisa de ordem estável e, para boa performance, de índices nas colunas usadas na ordenação.

Leia também

Criação de Apps

Rate limit: o que é e como lidar com o limite de requisições

O limite de requisições protege a API, e seu app precisa estar preparado para esbarrar nele.

· 2 min de leitura
Criação de Apps

O app ficou lento com mais usuários? Como escalar sem quebrar

O que fazer quando o aplicativo começa a travar com o crescimento do número de usuários, em ordem de prioridade.

· 5 min de leitura
Criação de Apps

Métodos HTTP: GET, POST, PUT e DELETE explicados para iniciantes

Os métodos HTTP dizem ao servidor o que você quer fazer com um recurso.

· 2 min de leitura
Criação de Apps

Idempotência em APIs: como evitar cobranças e pedidos duplicados

Se a mesma requisição chegar duas vezes, o resultado precisa ser o mesmo de quando chega uma.

· 2 min de leitura

Deixe seu comentário