Paginação por Cursor

A resposta contém `items` e `next_cursor`. O cliente não interpreta o token; envia exatamente no próximo pedido. O servidor pode codificar chave de ordenação, ID, partição, filtro e assinatura. Base64 não é segurança; tokens com dados sensíveis precisam de proteção ou referência server-side. O cursor deve estar ligado aos parâmetros da consulta para impedir uso com filtro diferente. Se a primeira chamada usa `room=sala&sort=created_at`, a continuação precisa preservar. Alterar o filtro deve iniciar nova paginação. O contrato define `null` quando termina. Uma página vazia pode ainda ter continuação em sistemas particionados, portanto o cliente deve seguir o token até ausência, não parar apenas por zero itens.

O cursor pode representar a última chave vista. A consulta usa `WHERE (created_at,id) > (?,?) ORDER BY created_at,id LIMIT 100`. O ID desempata timestamps iguais. Esse método evita que inserções anteriores desloquem offsets. É eficiente com índice adequado. A ordenação precisa ser total e imutável durante a leitura. Se o campo muda, itens podem aparecer novamente ou sumir. Para telemetria, `(timestamp,event_id)` funciona. Para dispositivos ordenados por nome editável, é menos estável. O banco precisa de índice composto. O cursor não deve expor SQL diretamente. A API pode assinar o token. O uso reverso exige cursor e operador correspondentes.

Serviços distribuídos devolvem token que contém progresso entre partições. Azure Table Storage retorna cabeçalhos de continuação com próxima partição e row key; Cosmos DB usa `x-ms-continuation`. O token pode mudar de formato e deve ser tratado como opaco. O SDK normalmente gerencia. O servidor pode expirar tokens após mudanças, upgrades ou retenção. O cliente precisa salvar junto com consulta, versão e timestamp. Uma integração que persiste o token por meses sem política pode falhar. Quando recebe `InvalidContinuationToken`, deve reiniciar ou ressincronizar conforme o contrato, evitando duplicar efeitos. Para leitura, deduplicação por ID ajuda.

Em feeds de eventos, o cursor representa sequência ou offset. O cliente lê 500 eventos, grava o cursor depois de processar e continua. Isso aproxima consumo de log. A confirmação local precisa ser atômica com o efeito quando possível. Se grava o cursor antes, pode perder; depois, pode repetir. Processamento idempotente resolve repetição. O servidor precisa definir retenção. Se o cursor é mais antigo que 7 dias e o log retém 7 dias, responde `410 Gone` ou código próprio e exige snapshot. Em automação, uma sincronização robusta combina snapshot atual e eventos a partir de uma posição consistente.