Paginação em APIs: como percorrer uma coleção

O que significa receber uma coleção paginada

Uma coleção paginada entrega resultados em partes, em vez de reuni-los em uma única resposta. Para percorrê-la, é preciso solicitar e processar cada parte conforme as regras do endpoint e identificar quando o percurso termina. A Sensedia recomenda o uso de paginação em serviços que devolvem grandes quantidades de dados; essa é uma recomendação, não uma regra sobre o funcionamento de todas as APIs. Fonte: https://www.sensedia.com.es/post/api-buenas-practicas-de-paginacion-y-filtros.

O mecanismo varia conforme o serviço. Antes de implementar, consulte a documentação para saber como iniciar a leitura, qual informação permite continuar e qual condição indica o fim. Uma resposta correta não significa, por si só, que a coleção inteira foi percorrida. O ponto principal é distinguir entre receber uma resposta válida e completar a sequência de solicitações prevista pelo contrato.

Essa distinção também orienta a revisão do código. A lógica deve usar os sinais descritos para a operação específica, em vez de supor que um nome de parâmetro, um formato de resposta ou uma forma de navegação seja comum a todos os serviços.

• Localize a documentação da operação que será consumida, não apenas uma descrição geral da API.
• Anote como iniciar a consulta, como reconhecer a continuação e como identificar o encerramento.
• Trate qualquer comportamento não documentado como uma dúvida a esclarecer, não como uma convenção garantida.

Um procedimento prático, condicionado ao contrato

Organize a implementação em um ciclo, substituindo cada elemento pelo que a documentação técnica do endpoint especificar. Este esquema não define nomes de parâmetros nem uma estrutura universal de resposta. Seu objetivo é separar as decisões: quais resultados processar, o que verificar para continuar e qual sinal permite encerrar.

Uma sequência de trabalho pode começar pela identificação da operação e dos parâmetros iniciais obrigatórios. Em seguida, faça a solicitação inicial e processe os resultados recebidos. Examine então as informações de continuação descritas pelo serviço. Se indicarem que há outra parte, prepare a solicitação seguinte conforme o contrato e processe os novos resultados. Repita essa avaliação até que a condição de encerramento documentada seja atendida.

Em pseudocódigo: «iniciar conforme o contrato; enquanto houver continuação indicada, solicitar a próxima parte pelo mecanismo documentado e processar os resultados; parar quando o sinal indicar o fim». Não invente uma URL, um número de página ou um cursor se o contrato não especificar esse procedimento. Se alguma etapa não estiver definida, esclareça-a antes de implementar.

Ao transformar o esquema em código, mantenha explícita a condição que encerra o ciclo. Isso facilita revisar se a execução terminou porque o serviço indicou que não há mais resultados ou por outro motivo, como uma interrupção. Não use apenas a chegada de uma resposta como sinal de conclusão, a menos que essa seja a condição definida para a operação.

• Confirme quais dados devem acompanhar a solicitação inicial.
• Use somente o mecanismo de continuação descrito para o endpoint.
• Separe o processamento dos resultados da decisão de solicitar outra parte.
• Registre qual condição documentada fez o ciclo terminar.

Um exemplo específico: New Relic REST API v2

A documentação da New Relic REST API v2 informa que, quando os dados são paginados, a resposta inclui um cabeçalho Link que indica o número de páginas e qual delas está sendo consultada. Esse comportamento é específico à API documentada e não demonstra que outros serviços usem o mesmo cabeçalho. Fonte: https://docs.newrelic.com/es/docs/apis/rest-api-v2/basic-functions/pagination-api-output/.

Ao usar essa referência, compare a informação descrita com a operação que pretende consumir. Não deduza como construir a próxima solicitação apenas por conhecer o total de páginas e a página consultada; siga as instruções aplicáveis da documentação da New Relic. O exemplo serve para mostrar por que é necessário ler o contrato da API concreta antes de definir a lógica de navegação.

Em outra API, o sinal de continuação pode ser diferente ou a documentação pode apresentar outro procedimento. A evidência disponível aqui não permite afirmar qual mecanismo seria usado nesse caso. Portanto, não copie a implementação de um serviço para outro sem verificar a documentação correspondente.

• O cabeçalho Link descrito é uma informação da New Relic REST API v2, não uma regra geral.
• Verifique a documentação da operação que será chamada antes de decidir como montar a solicitação seguinte.

O que verificar se a leitura for interrompida ou repetir registros

Se o processo parar antes de alcançar a condição de encerramento, não marque a importação como completa. Registre a interrupção e confira na documentação como continuar. Não presuma que uma posição ou um cursor possa ser mantido ou recuperado. Se o serviço não explicar como retomar, peça esclarecimentos em vez de tratar o último valor observado como um ponto de retomada válido.

Na revisão de uma interrupção, diferencie o que foi confirmado do que permanece desconhecido. Por exemplo, um registro local da última solicitação pode ajudar a descrever em que ponto a execução parou, mas não demonstra que o serviço aceite continuar dali. A possibilidade de retomar e as informações necessárias para isso dependem do contrato técnico específico.

Se registros parecerem repetidos entre partes, compare os identificadores disponíveis e consulte o contrato e o histórico da execução antes de decidir o que fazer. Se a aplicação tiver uma regra própria para tratar identificadores repetidos, documente-a e verifique se ela não descarta dados que deveriam ser mantidos. Não presuma que o serviço garanta a ausência de repetições.

Essas verificações ajudam a diagnosticar a execução, mas não estabelecem uma estratégia universal de retomada ou deduplicação. A abordagem depende das regras do endpoint e das necessidades da integração. Evite apresentar uma decisão local de tratamento de dados como uma garantia fornecida pela API.

• Não classifique uma execução interrompida como concluída.
• Não considere um cursor ou uma posição local um ponto de retomada válido sem respaldo na documentação.
• Antes de remover registros que parecem repetidos, confira os identificadores e a regra adotada pela aplicação.

Verificações para revisar o resultado

Como prática geral de engenharia, registre a operação executada, os horários de início e término, o número de solicitações e o sinal interpretado como encerramento. Esses dados ajudam a revisar a execução, mas não provam automaticamente que a leitura está completa. Mantenha os registros claros o bastante para distinguir os sinais recebidos do serviço das decisões tomadas pela aplicação.

Se o serviço fornecer uma contagem de referência, compare-a com os itens contabilizados pela integração e investigue eventuais diferenças. Uma contagem não demonstra, por si só, que todos os itens esperados foram recebidos; tampouco a ausência de identificadores repetidos prova que não faltam registros. Mantenha claro o que veio do serviço e o que foi calculado localmente.

Ao revisar uma execução, confira também se o ciclo realmente parou por causa da condição documentada e se os resultados recebidos foram processados. Se a aplicação terminar por erro, limite local ou interrupção, registre esse motivo de forma distinta. Assim, uma revisão posterior não confunde um encerramento previsto pelo endpoint com um percurso incompleto.

Essas verificações são controles de revisão, não garantias de integridade oferecidas pelo serviço. Quando a documentação não fornece uma contagem ou um sinal adicional, não invente uma confirmação. Descreva a evidência disponível e registre o que ainda não pode ser confirmado.

• Registre a condição observada ao encerrar o ciclo.
• Diferencie as informações devolvidas pela API das contagens e decisões locais.
• Investigue diferenças sem presumir que uma contagem isolada prove que todos os itens foram recebidos.

O que verificar em uma integração com Apification Cloud

A Apification permite integrar o Cloud e seus serviços por meio de REST API, OpenAPI, webhooks, iframe e JavaScript. Essas opções descrevem recursos de integração, mas não especificam como uma operação concreta faz paginação ou quais parâmetros, sinais de continuação ou garantias oferece.

Antes de automatizar a leitura de recursos, identifique o contrato técnico da operação: endpoint, forma documentada de continuar e condição de encerramento. Não substitua regras ausentes por uma convenção inventada. Se a documentação aplicável não esclarecer uma etapa, obtenha essa informação antes de definir o comportamento da integração.

O Apification Cloud permite organizar arquivos, serviços e projetos em um espaço versionado e compartilhável. Esse recurso não implica que um endpoint use um tipo específico de paginação. Da mesma forma, a disponibilidade de opções de integração não deve ser interpretada como uma especificação para cada operação ou como garantia de um comportamento de paginação.

Ao documentar uma integração, descreva separadamente o que a plataforma oferece e o que o contrato da operação estabelece. Essa distinção ajuda a evitar que uma capacidade geral, como a integração por API, seja confundida com detalhes que precisam ser confirmados para o endpoint consumido.

• Confirme o contrato técnico da operação específica que pretende integrar.
• Não deduza um tipo de paginação a partir da disponibilidade de REST API ou OpenAPI.
• Registre as dúvidas pendentes sobre continuação e encerramento antes de automatizar o percurso.

Perguntas frequentes