Migrando a paginação antiga

Para garantir a melhor experiência e performance, estamos migrando nossa paginação de page para cursor. Essa mudança traz um ganho significativo, especialmente para grandes volumes de dados.

A paginação por cursor oferece mais estabilidade e eficiência, pois aponta para uma posição fixa na lista de resultados. Isso minimiza problemas caso os dados sejam alterados durante a sua iteração.

Incentivamos você a migrar para o novo método para aproveitar todos os benefícios de uma integração mais robusta e performática.

❗️

Esta migração não é só uma recomendação de uso

A migração para a paginação por cursor é crucial para a excelência das operações que a PipeRun oferece. Por isso, a adoção deste novo método não é apenas uma recomendação, mas sim um passo que se tornará obrigatório em breve.

1. Paginação Antiga (page)

Neste modelo, a navegação entre as páginas era feita de forma sequencial, utilizando o parâmetro page. Você informava o número da página que desejava acessar (page=1, page=2, etc.) para buscar o próximo conjunto de dados. Então você tinha uma requisição assim:

GET /v1/deals?show=10&page=1

E recebia esta resposta:

{
  "success": true,
  "message": "OK",
  "data": [{...},{...}],
  "meta": {
    "total": 50,
    "count": 10,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 5,
    "links": {
      "next": "https://api.pipe.run/v1/deals?show=1&page=2"
    }
  }
}

Para navegar em todas as paginas você iria iterar pagina a pagina, incrementando o número da pagina até atingir o limite de paginas ou não ter mais dados para serem recuperados. Exemplo de pseudo código em Python:

pagina = 1
while True:
    response = api.get(f"/deals?show=10&page={pagina}")
    // processamento dos dados
    if pagina >= response["meta"]["total_pages"] or not response["data"]:
        break
    pagina += 1

2. Paginação Nova (cursor)

A paginação por cursor oferece um método mais robusto e eficiente, ideal para lidar com grandes conjuntos de dados. Em vez de usar um número de página, você usa o valor de cursor.next retornado na resposta da API para buscar a próxima página. Esse cursor atua como um "marcador" que aponta para o último item do conjunto de dados anterior, garantindo uma busca contínua e precisa, mesmo que os dados sejam alterados durante a sua navegação. Então, para este novo formato você terá uma requisição assim:

GET /v1/deals?show=10&cursor=

Note que o conteúdo da primeira requisição é uma string vazia, e isto é proposital.

Obtendo uma resposta como a descrita abaixo:

{
  "success": true,
  "message": "OK",
  "data": [{...},{...}],
  "meta": {
    "cursor": {
      "current": null,
      "prev": null,
      "next": "eyJpZCI7NDA2NTA3UTYsIl9wb2ludHNUb05leHRJdGVtRyI6dHJ1ZX0",
      "count": null
    }
  }
}

Para navegar em todas as paginas você irá iterar pagina a pagina, usando a hash cursor.next da requisição anterior, até ela ser null ou não ter mais dados para serem recuperados. Neste exemplo, a segunda requisição seria assim:

GET /v1/deals?show=10&cursor=eyJpZCI7NDA2NTA3UTYsIl9wb2ludHNUb05leHRJdGVtRyI6dHJ1ZX0

Exemplo de pseudo código em Python:

cursor = ""  # começa como string vazia
while True:
    response = api.get(f"/deals?show=10&cursor={cursor}")
    // processamento dos dados
    cursor = response["meta"]["cursor"]["next"]
    if not cursor or not response["data"]:
        break

3. O que muda em relação ao sistema antigo?

Diferenças Práticas

Por quê mudar?

• Melhor para grandes volumese menos erros se os dados mudam enquanto você percorre
• Mais escalável O cursor aponta para um ponto fixo do resultado, e não depende de contagens que podem variar enquanto a lista muda.