Paginação

Todos os endpoints de listagem retornam seus resultados em páginas. A página é selecionada com o parâmetro de query string range opcional, e o número total de registros é retornado nos cabeçalhos da resposta.

Sintaxe

O parâmetro range é um array JSON com duas posições, começando em zero: o primeiro e o último registro a retornar. Ambas as posições são inclusivas.

range=[0,99]

O exemplo acima retorna os primeiros 100 registros. A próxima página seria range=[100,199], e assim por diante.

Quando range é omitido, a API retorna os primeiros 10 registros, como se range=[0,9] tivesse sido enviado.

Um erro 400 Bad Request é retornado quando o array não contém exatamente dois elementos, ou quando a primeira posição é maior que a última.

Resposta

O corpo da resposta é um array JSON com os registros da página solicitada. Ele não fica encapsulado em nenhum outro objeto.

O número total de registros que atendem ao filtro é retornado em dois cabeçalhos da resposta:

Quando nenhum registro corresponde, o corpo é um array vazio ([]) e os cabeçalhos são X-Total-Count: 0 e Content-Range: campaigns 0-0/0. Solicitar uma página além do último registro também retorna um array vazio.

Percorrer todas as páginas

Para ler todos os registros, solicite páginas consecutivas até ter lido X-Total-Count registros, ou até que uma página retorne menos registros do que o solicitado. Use sempre uma ordenação, para que as páginas sejam consistentes entre as solicitações. Por exemplo, em Python:

import requests

url = "https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers"
headers = {"Authorization": "Bearer API_KEY_TOKEN"}
page_size = 100
start = 0
numbers = []

while True:
    params = {"sort": '["id","ASC"]', "range": f"[{start},{start + page_size - 1}]"}
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    page = response.json()
    numbers.extend(page)
    total = int(response.headers["X-Total-Count"])
    start += page_size
    if len(page) < page_size or start >= total:
        break

print(f"Read {len(numbers)} of {total} numbers")

Recomendamos páginas de até algumas centenas de registros. Páginas maiores levam mais tempo para serem geradas e transferidas, e têm mais chance de atingir tempos limite em redes lentas. Tenha em mente os limites de taxa ao ler muitas páginas em um loop.