Uma API que retorna listas precisa limitar a quantidade de itens entregue em cada resposta. Sem paginação, uma consulta pode consumir recursos desnecessários, aumentar a latência e dificultar o uso por quem integra o serviço. A decisão não se resume a escolher uma sintaxe: o mecanismo afeta quais itens cada consumidor vê quando os dados mudam, como navega e quais garantias pode esperar.
As duas opções mais comuns são a paginação por offset, que indica quantos registros devem ser ignorados, e a paginação por cursor, que usa uma referência para continuar a partir de uma posição. A escolha depende do padrão de uso e das garantias necessárias, não de uma estratégia ser universalmente melhor.
O que uma resposta paginada deve garantir
Antes de escolher o mecanismo, defina o contrato da coleção. No mínimo, decida o tamanho máximo da página, a ordenação dos itens, como solicitar a página seguinte e o que acontece quando não há mais resultados. Também convém especificar como a paginação se combina com filtros e ordenação.
A ordenação deve ser determinística. Ordenar apenas por uma data, por exemplo, pode deixar vários registros empatados. Se a ordenação não definir como resolver esses empates, solicitações diferentes podem retornar itens em posições distintas. Acrescentar um critério único, como o identificador do registro, permite estabelecer uma sequência inequívoca.
Uma resposta útil pode incluir os itens e uma referência para continuar, além de metadados como o tamanho efetivo da página. Nem todos os clientes precisam saber o total de resultados: calculá-lo pode ter um custo e, em conjuntos que mudam com frequência, o total pode ficar desatualizado rapidamente. Inclua apenas as informações necessárias para o caso de uso.
Paginação por offset: simples para acessar uma posição
Com offset, o cliente solicita um limite e quantos itens devem ser ignorados. Uma solicitação conceitual seria: “retorne 20 itens a partir do registro 40”. É um modelo fácil de explicar e adequado a interfaces com páginas numeradas, saltos para uma página específica ou acesso direto a resultados mais adiante na lista.
Sua principal vantagem é a simplicidade do contrato. Os clientes podem criar links para páginas, e as equipes conseguem raciocinar sobre intervalos. Também pode ser suficiente para coleções pequenas ou relativamente estáveis, sobretudo quando a navegação direta é um requisito real.
A limitação aparece quando os dados mudam entre as solicitações. Suponha que o cliente carregue a primeira página e, antes de pedir a seguinte, um item seja inserido no início da ordenação. O offset posterior pode incluir novamente um registro já visto. Se um item for removido antes da posição solicitada, outro que ainda não havia sido entregue pode ser ignorado. O offset, por si só, não garante uma visão consistente de uma coleção dinâmica.
Além disso, solicitar posições muito profundas pode exigir percorrer ou descartar muitos registros, dependendo do banco de dados, da consulta e dos índices. Isso não ocorre da mesma forma em todos os sistemas: é preciso medir o comportamento com consultas representativas. Se as páginas profundas ficarem lentas, limite os saltos ou avalie outro mecanismo.
Paginação por cursor: continuar a partir de uma posição
Na paginação por cursor, a resposta fornece uma referência que o cliente envia para obter o próximo trecho. O cursor representa uma posição dentro de uma ordenação; pode se basear, por exemplo, no valor de ordenação e em um identificador que resolva empates. O cliente não precisa saber como essa referência é construída internamente.
Para funcionar de maneira previsível, a consulta deve manter a mesma ordenação entre as solicitações. Um cursor baseado em uma data precisa de um critério adicional se várias linhas compartilharem essa data. Mudanças simultâneas ainda podem afetar o que aparece nas páginas seguintes, mas uma estratégia baseada na posição ordenada costuma evitar os deslocamentos típicos de ignorar uma quantidade de linhas. Isso não equivale necessariamente a um retrato imutável dos dados: essa garantia exige um comportamento adicional, que deve ser projetado e documentado.
O cursor deve ser tratado como opaco para o consumidor. Ele pode codificar dados de posição, mas codificar não significa criptografar nem proteger. Não inclua informações sensíveis sem a proteção adequada e valide se o cursor é válido para a consulta, o usuário e o contexto de autorização correspondentes. Defina também se ele expira e qual resposta o cliente recebe quando deixa de ser utilizável.
Essa opção é adequada para percursos sequenciais, feeds, catálogos grandes e processos que avançam pelos resultados sem saltar para uma página arbitrária. Em contrapartida, dificulta a navegação direta e exige cuidado com o formato, a validação e a compatibilidade dos cursores.
Critérios práticos para escolher
Avalie a experiência de que o consumidor precisa e as características do conjunto de dados. A decisão pode ser resumida assim:
- Escolha offset se páginas numeradas ou saltos diretos forem importantes, o conjunto for limitado ou as mudanças durante a navegação tiverem impacto aceitável.
- Escolha cursor se os resultados forem percorridos sequencialmente, o conjunto puder crescer muito ou inserções e exclusões tornarem indesejáveis os deslocamentos entre páginas.
- Compare o custo real com consultas e tamanhos representativos. A estratégia, os índices, os filtros e o banco de dados influenciam o desempenho.
- Considere o padrão de integração: uma exportação em lote pode precisar avançar de forma confiável; uma interface administrativa talvez valorize o salto para uma página específica.
Não misture os dois modelos sem explicar seu alcance. Oferecer offset para algumas consultas e cursor para outras pode fazer sentido, mas cada coleção deve documentar claramente seu contrato. Também não apresente um cursor como garantia de consistência total se o projeto apenas conserva uma posição e a coleção continua mudando.
Filtros, ordenação e limites: o contrato completo
O cursor e a página seguinte devem corresponder aos mesmos filtros e à mesma ordenação que originaram a primeira resposta. Se o cliente alterar esses parâmetros, deve iniciar um novo percurso, em vez de reutilizar uma referência que representa outra consulta. A API pode rejeitar essa combinação ou emitir cursores que incluam o contexto necessário para validá-la.
Documente um tamanho padrão e um máximo por solicitação. Um limite evita respostas excessivamente grandes, mas deve ser compatível com o consumo esperado e não obrigar o cliente a fazer chamadas em excesso. Especifique o que acontece com valores ausentes, inválidos ou acima do máximo: aplicar um limite ou retornar um erro são alternativas possíveis; o importante é manter um comportamento consistente.
A ordenação solicitada pelo usuário também precisa de restrições claras. Aceite somente campos e direções permitidos, estabeleça um critério determinístico para desempates e evite combinar acidentalmente uma mudança de ordenação com um cursor anterior. Esses detalhes reduzem resultados repetidos, omissões e consultas difíceis de otimizar.
Migrar sem interromper os consumidores existentes
Se uma API já oferece offset, alterar a resposta ou remover parâmetros pode quebrar aplicativos e integrações. Antes de migrar, identifique clientes, padrões de uso, páginas profundas e erros observados. Se não houver telemetria suficiente, instrumente as solicitações para descobrir quais parâmetros são usados, respeitando as políticas de privacidade e retenção aplicáveis.
- Defina o novo contrato: ordenação, filtros, tamanho máximo, formato opaco do cursor e comportamento diante de cursores inválidos.
- Introduza a compatibilidade de forma explícita: por exemplo, com uma nova rota ou parâmetro, ou uma transição documentada que mantenha temporariamente o mecanismo anterior.
- Teste mudanças simultâneas, empates na ordenação, a última página, filtros alterados e cursores malformados ou reutilizados fora do contexto.
- Acompanhe a adoção e o desempenho antes de remover a opção antiga. Comunique as mudanças e forneça instruções de atualização aos consumidores.
Evite que uma resposta mude de significado silenciosamente conforme o cliente ou que o servidor interprete um parâmetro ambíguo de duas maneiras. A compatibilidade deve poder ser verificada, e as datas ou condições para descontinuação precisam ser documentadas, não presumidas.
Lista de verificação para a decisão
- Os consumidores precisam saltar diretamente para uma página numerada?
- Os dados mudam durante a navegação, e qual é o impacto de repetições ou omissões?
- A ordenação é determinística e tem um critério único para resolver empates?
- Consultas profundas e tamanhos de página realistas foram medidos?
- Filtros, limites, erros e reutilização de cursores estão definidos?
- Há uma estratégia de compatibilidade e uma forma de acompanhar a adoção?
Se a navegação direta for essencial e o conjunto for gerenciável, offset pode ser uma escolha razoável. Se predominar o percurso sequencial e o volume ou as mudanças tornarem frágeis os deslocamentos, cursor costuma ser mais adequado. Documente primeiro as garantias necessárias e só então escolha o mecanismo: assim, a API atende às necessidades reais dos consumidores e pode evoluir sem surpresas.