Paginación

Todos los endpoints de listado devuelven sus resultados en páginas. La página se selecciona con el parámetro de consulta range opcional, y la cantidad total de registros se devuelve en los encabezados de la respuesta.

Sintaxis

El parámetro range es un array JSON con dos posiciones, comenzando en cero: el primer y el último registro a devolver. Ambas posiciones están incluidas.

range=[0,99]

El ejemplo anterior devuelve los primeros 100 registros. La página siguiente sería range=[100,199], y así sucesivamente.

Cuando se omite range, la API devuelve los primeros 10 registros, como si se hubiera enviado range=[0,9].

Se devuelve un error 400 Bad Request cuando el array no contiene exactamente dos elementos, o cuando la primera posición es mayor que la última.

Respuesta

El cuerpo de la respuesta es un array JSON con los registros de la página solicitada. No está envuelto en ningún otro objeto.

La cantidad total de registros que cumplen el filtro se devuelve en dos encabezados de la respuesta:

Cuando ningún registro coincide, el cuerpo es un array vacío ([]) y los encabezados son X-Total-Count: 0 y Content-Range: campaigns 0-0/0. Solicitar una página posterior al último registro también devuelve un array vacío.

Recorrer todas las páginas

Para leer todos los registros, solicita páginas consecutivas hasta haber leído X-Total-Count registros, o hasta que una página devuelva menos registros que los solicitados. Usa siempre un ordenamiento, para que las páginas sean consistentes entre solicitudes. Por ejemplo, en 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 hasta unos pocos cientos de registros. Las páginas más grandes tardan más en generarse y transferirse, y es más probable que superen los tiempos de espera en redes lentas. Ten en cuenta los límites de solicitudes al leer muchas páginas en un bucle.