Paginazione
Tutti gli endpoint di elenco restituiscono i risultati in pagine. La pagina viene selezionata con il parametro di query range opzionale, e il numero totale di record viene restituito nelle intestazioni della risposta.
Sintassi
Il parametro range è un array JSON con due posizioni a partire da zero: il primo e l'ultimo record da restituire. Entrambe le posizioni sono incluse.
range=[0,99]L'esempio precedente restituisce i primi 100 record. La pagina successiva sarebbe range=[100,199], e così via.
Quando range viene omesso, l'API restituisce i primi 10 record, come se fosse stato inviato range=[0,9].
Viene restituito un errore 400 Bad Request quando l'array non contiene esattamente due elementi, o quando la prima posizione è maggiore dell'ultima.
Risposta
Il corpo della risposta è un array JSON con i record della pagina richiesta. Non è racchiuso in nessun altro oggetto.
Il numero totale di record che corrispondono al filtro viene restituito in due intestazioni della risposta:
| Intestazione | Esempio | Descrizione |
|---|---|---|
X-Total-Count | 1234 | Numero totale di record che corrispondono al filtro, considerando tutte le pagine. |
Content-Range | campaigns 0-99/1234 | Il nome della risorsa, le posizioni del primo e dell'ultimo record restituiti, e il numero totale di record. |
Quando nessun record corrisponde, il corpo è un array vuoto ([]) e le intestazioni sono X-Total-Count: 0 e Content-Range: campaigns 0-0/0. Anche la richiesta di una pagina oltre l'ultimo record restituisce un array vuoto.
Scorrere tutte le pagine
Per leggere tutti i record, richiedi pagine consecutive finché non hai letto X-Total-Count record, oppure finché una pagina non restituisce meno record di quelli richiesti. Usa sempre un ordinamento, così le pagine sono coerenti tra una richiesta e l'altra. Ad esempio, in 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")Ti consigliamo pagine di al massimo qualche centinaio di record. Le pagine più grandi richiedono più tempo per essere generate e trasferite, ed è più probabile che vadano in timeout sulle reti lente. Tieni presenti i limiti di frequenza quando leggi molte pagine in un ciclo.
/v1/accounts/ACCOUNT_ID/campaigns
curl -G 'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns' \
-H 'Authorization: Bearer API_KEY_TOKEN' \
--data-urlencode 'sort=["name","ASC"]' \
--data-urlencode 'range=[0,99]'Intestazioni della risposta
{
"Content-Range": "campaigns 0-99/1234",
"X-Total-Count": "1234"
}
