O que é Cursor de paginação?

Uma referência para continuar a consulta

Cursor de paginação é uma referência usada para continuar a leitura de uma coleção. A API pode devolver um token de continuação ou orientar o uso de um identificador recebido na página anterior. A chamada seguinte fornece essa referência conforme o contrato.

O cursor evita que a integração precise tratar toda continuação como um número de página. Ele pode representar os valores de ordenação do último item, um estado temporário no serviço ou outra estratégia. Sua aparência não revela necessariamente o mecanismo utilizado.

Um cursor opaco deve ser reutilizado sem interpretação. Já algumas APIs documentam explicitamente parâmetros baseados no identificador de um objeto. Nos dois casos, você precisa seguir a convenção do serviço, sem construir um valor por suposição.

Cursor de API e cursor SQL

O nome também aparece no banco de dados. No PostgreSQL, DECLARE cria um cursor SQL, e FETCH recupera partes do resultado associado. Esse mecanismo tem condições próprias de sessão e transação, diferentes do contrato de paginação apresentado pela API.

Receber um cursor pela API não comprova que o servidor mantém um cursor SQL aberto. A referência pode conter apenas os valores usados para montar a próxima consulta. Você precisa distinguir o que a API promete ao cliente da implementação escolhida para buscar os registros.

Um exemplo de resposta

{
"itens": [{"id": 7}, {"id": 12}],
"proximo_cursor": "REFERENCIA_FICTICIA",
"tem_mais": true
}

O exemplo apenas ilustra um contrato possível. A integração envia o valor de proximo_cursor na chamada seguinte usando o parâmetro documentado. O nome do campo, o limite e o sinal de término variam entre APIs.

Codificar um valor em base64 não o torna secreto nem garante sua integridade. O serviço precisa validar a referência recebida e continuar aplicando as permissões do perfil autenticado. Possuir um cursor não deve conceder acesso adicional à coleção.

Ordenação e ponto de continuação

Uma implementação baseada em chave pode continuar depois do último par de valores ordenados, como data e identificador. Se a página terminar no meio de um grupo com a mesma data, buscar apenas datas posteriores omitiria os itens restantes daquele grupo. O identificador usado como desempate permite distinguir a posição dentro dele, desde que a consulta aplique a mesma ordenação na continuação.

Essa estratégia pode evitar alguns deslocamentos causados por novas linhas antes do ponto já percorrido. Ainda assim, mudanças nos campos de ordenação, exclusões e filtros podem alterar os resultados. Cursor não é uma promessa universal de leitura imutável.

O cursor também pode expirar, e repetir a mesma referência pode observar uma coleção diferente. Defina como retomar uma exportação interrompida conforme o suporte da API, mantendo o registro do que já foi concluído. Guardar apenas o último token não resolve todos esses casos.

O cursor pertence à consulta

Alterar filtros, ordenação ou perfil autenticado enquanto reutiliza uma referência pode ser inválido. Alguns serviços incluem essas condições no token, enquanto outros esperam que a integração as preserve. Confira o contrato antes de misturar parâmetros de consultas distintas.

O sinal de término também varia. Uma API pode omitir a continuação, devolver nulo ou fornecer um campo booleano. Não trate qualquer ausência como fim sem verificar se a resposta foi válida e completa.

Como testar a sequência

Prepare uma coleção conhecida com vários registros na mesma data e faça uma página terminar no meio desse grupo. Ao continuar, compare os identificadores para conferir se todos aparecem uma única vez no conjunto estável. Depois, teste as mudanças e interrupções previstas para a integração, incluindo a resposta a uma referência inválida ou expirada.

O verbete de paginação reúne as condições necessárias para interpretar o percurso completo.

Aplicação na formação

Developer Workspace

O cursor de paginação indica como continuar a consulta nas APIs que entregam listas em partes.

Conhecer a formação →