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
- Defina um tamanho padrão e um máximo. Não deixe o cliente pedir 100 mil itens.
- Garanta uma ordenação determinística. Sem ordem definida, a mesma consulta pode devolver resultados em sequências diferentes.
- Crie índices nas colunas de ordenação e filtro.
- Devolva, na resposta, informações para continuar: o cursor ou o número da próxima página, e se há mais itens.
- Documente os parâmetros e os limites para quem consome a API.
- 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.