Cursor de paginação

Definição

Cursor de paginação é a referência de posição devolvida por uma API para buscar a próxima parte de um conjunto de resultados. A resposta informa onde a leitura parou, e a chamada seguinte parte desse ponto.

Receber e reutilizar a referência

A primeira resposta traz um lote de itens e um cursor. A próxima chamada envia esse cursor de volta e recebe o lote seguinte. Repetir o processo percorre a coleção inteira sem precisar recomeçar do início.

curl 'https://api.exemplo.com/registros?limit=10&cursor=eyJwb3MiOjEw'
# Resposta: registros 11 a 20 e um novo cursor

Cursor é opaco para o consumidor

O valor do cursor costuma ser codificado para não expor a posição, e o servidor o decodifica na chegada. Repetir o mesmo cursor deve devolver o mesmo ponto de partida, e seguir o cursor recebido deve avançar para o trecho seguinte sem recomeçar do início.

O cursor não é um número de página nem um valor que o consumidor deva construir ou interpretar. Ele funciona como uma marca de posição emitida pelo servidor. Alterar o valor por conta própria pode apontar para uma posição inexistente e interromper a navegação.

Falha comum e como verificar

A falha mais comum é o consumidor tratar o cursor como número de página e tentar montar o próprio valor. Alterar um caractere do cursor costuma apontar para uma posição inexistente, e a API responde com erro ou com a sequência interrompida. Para verificar, guarde o cursor recebido, use-o na chamada seguinte e confira se o servidor retoma exatamente a partir do último item entregue, sem repetição nem buraco entre os lotes. Depois, envie um cursor adulterado e observe a resposta: a falha aparece na hora e mostra por que o valor deve ser consumido como opaco.

Aplicação na formação

Developer Workspace

Na Formação Developer Workspace, o cursor de paginação aparece nas APIs que devolvem listas longas sem sobrecarregar a resposta.

Conhecer a formação →