Pagination
Tous les points de terminaison de listage renvoient leurs résultats par pages. La page est sélectionnée avec le paramètre de requête facultatif range, et le nombre total d’enregistrements est renvoyé dans les en-têtes de la réponse.
Syntaxe
Le paramètre range est un tableau JSON contenant deux positions commençant à zéro : le premier et le dernier enregistrement à renvoyer. Les deux positions sont incluses.
range=[0,99]L’exemple ci-dessus renvoie les 100 premiers enregistrements. La page suivante serait range=[100,199], et ainsi de suite.
Lorsque range est omis, l’API renvoie les 10 premiers enregistrements, comme si range=[0,9] avait été envoyé.
Une erreur 400 Bad Request est renvoyée lorsque le tableau ne contient pas exactement deux éléments, ou lorsque la première position est supérieure à la dernière.
Réponse
Le corps de la réponse est un tableau JSON contenant les enregistrements de la page demandée. Il n’est encapsulé dans aucun autre objet.
Le nombre total d’enregistrements correspondant au filtre est renvoyé dans deux en-têtes de réponse :
| En-tête | Exemple | Description |
|---|---|---|
X-Total-Count | 1234 | Nombre total d’enregistrements correspondant au filtre, toutes pages confondues. |
Content-Range | campaigns 0-99/1234 | Le nom de la ressource, les positions du premier et du dernier enregistrement renvoyés, et le nombre total d’enregistrements. |
Lorsqu’aucun enregistrement ne correspond, le corps est un tableau vide ([]) et les en-têtes sont X-Total-Count: 0 et Content-Range: campaigns 0-0/0. Demander une page au-delà du dernier enregistrement renvoie également un tableau vide.
Parcourir toutes les pages
Pour lire tous les enregistrements, demandez des pages consécutives jusqu’à avoir lu X-Total-Count enregistrements, ou jusqu’à ce qu’une page renvoie moins d’enregistrements que demandé. Utilisez toujours un ordre de tri, afin que les pages soient cohérentes d’une requête à l’autre. Par exemple, 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")Nous recommandons des pages de quelques centaines d’enregistrements au maximum. Les pages plus grandes sont plus longues à générer et à transférer, et risquent davantage d’atteindre les délais d’expiration sur les réseaux lents. Tenez compte des limites de débit lorsque vous lisez de nombreuses pages dans une boucle.
/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]'En-têtes de réponse
{
"Content-Range": "campaigns 0-99/1234",
"X-Total-Count": "1234"
}
