Paginacja

Wszystkie endpointy zwracające listy zwracają wyniki w postaci stron. Strona jest wybierana za pomocą opcjonalnego parametru zapytania range, a całkowita liczba rekordów jest zwracana w nagłówkach odpowiedzi.

Składnia

Parametr range to tablica JSON z dwiema pozycjami liczonymi od zera: pierwszego i ostatniego zwracanego rekordu. Obie pozycje są uwzględniane.

range=[0,99]

Powyższy przykład zwraca pierwsze 100 rekordów. Następną stroną byłoby range=[100,199] i tak dalej.

Gdy parametr range zostanie pominięty, API zwraca pierwsze 10 rekordów, tak jakby wysłano range=[0,9].

Błąd 400 Bad Request jest zwracany, gdy tablica nie zawiera dokładnie dwóch elementów lub gdy pierwsza pozycja jest większa niż ostatnia.

Odpowiedź

Treść odpowiedzi to tablica JSON z rekordami żądanej strony. Nie jest opakowana w żaden inny obiekt.

Całkowita liczba rekordów pasujących do filtra jest zwracana w dwóch nagłówkach odpowiedzi:

Gdy żaden rekord nie pasuje, treść jest pustą tablicą ([]), a nagłówki to X-Total-Count: 0 i Content-Range: campaigns 0-0/0. Żądanie strony poza ostatnim rekordem również zwraca pustą tablicę.

Iterowanie po wszystkich stronach

Aby odczytać wszystkie rekordy, żądaj kolejnych stron, dopóki nie odczytasz X-Total-Count rekordów lub dopóki strona nie zwróci mniej rekordów niż żądano. Zawsze używaj kolejności sortowania, aby strony były spójne między żądaniami. Na przykład w 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")

Zalecamy strony o rozmiarze do kilkuset rekordów. Większe strony dłużej się generują i przesyłają, a w wolnych sieciach częściej przekraczają limity czasu. Pamiętaj o limitach żądań, gdy odczytujesz wiele stron w pętli.