Paginação e Ordenação

Paginação

A paginação com cursor permite limitar o número de resultados por requisição, além de fornecer uma maneira eficiente de percorrer grandes volumes de dados sem inconsistência de registros, comum com paginação por offset (page).

Se a rota da requisição for paginada, inclua o parâmetro cursor na string de consulta para especificar a posição de onde a busca começará.

Parâmetros de paginação com cursor

Exemplo de uso

Requisição inicial para buscar empresas (primeira página de resultados):

GET /v1/companies?cursor=

Resposta esperada:

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": 12345,
      "name": "Empresa XPTO",
      ...
    }
  ],
  "meta": {
    "cursor": {
      "current": null,
      "prev": null,
      "next": "eyJpZCI6MTQ3MTMxMTEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
      "count": null
    }
  }
}

Requisição para a próxima página

Para obter a próxima página de resultados, utilize o valor de meta.cursor.next conforme retornado na resposta anterior:

GET /v1/companies?cursor=eyJpZCI6MTQ3MTMxMTEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

✅ Observações:

• O parâmetro cursor substitui o uso de page, que não é mais necessário nesse modelo de paginação.
• O campo meta.cursor.next pode ser null caso não haja mais resultados disponíveis.
• A abordagem com cursor é recomendada para garantir consistência na navegação de dados que podem ser alterados com frequência.

Atenção:
A utilização de paginação por page vem sendo descontinuada para integrações via API, não utilize.

Ordenação

A ordenação permite que você manipule a ordem e a direção dos resultados de uma requisição.

Se a ordenação estiver disponível no endpoint que você deseja, você deve acrescentar uma string de consulta à URL de requisição. Para ordenar os resultados pela coluna "company_name" ,por exemplo, você precisa acrescentar o parâmetro "sort=company_name" em sua requisição.

O valor do sort é o nome da coluna pela qual você deseja ordenar seus resultados, e deve estar disponível na especificação de referência.

Você também pode especificar a direção da ordenação "desc=true" para ordenar de forma descendente, e "desc=false" para ordenar de forma ascendente.

Exemplo de requisição com resultados descendentes (DESC) "desc=true":

GET https://api.pipe.run/v1/companies?sort=company_name&desc=true

Exemplo de requisição com resultados ascendentes (ASC) "desc=false":

GET https://api.pipe.run/v1/companies?sort=company_name&desc=false

As ordenações disponíveis estão documentadas em cada endpoint na especificação de referência.

🚧

Atenção: Quando usado cursor e sort juntos alguns comportamentos inesperados podem ser observados. Por exemplo: Se o a sua base de dados possuir 2 pessoas com o mesmo nome e você ordenar o endpoint de pessoas por este parâmetro, o cursor pode suprimir uma das pessoas da sua listagem.