Les trois modes de pagination
| Mode | Avantage | Inconvénient |
|---|---|---|
| Offset / Limit | Simple, ?offset=200&limit=20 | Effondrement au-delà de 10 000 lignes |
| Page / Limit | Ergonomique, ?page=3 | Même limite que offset |
| Cursor | Stable, performant, ?cursor=... | Pas de saut direct à la page N |
Pourquoi l'offset ne tient pas
Demander la page 1000 avec un offset 100 000 force la base à lire 100 020 lignes pour n'en retourner que 20. À grande échelle, c'est un timeout garanti. Les API modernes utilisent toutes le curseur pour cette raison.
Pagination par curseur en détail
Un curseur encode la position de la dernière ligne lue (souvent un id ou un timestamp). À la requête suivante, l'API filtre directement sur "id > curseur_précédent" : aucune relecture inutile.
GET /v1/properties?limit=100&cursor=eyJpZCI6InRzLTk5OTk5In0
Authorization: Bearer ts_live_...
# Réponse
{
"data": [...],
"meta": {
"next_cursor": "eyJpZCI6InRzLTEwMDk5In0",
"has_more": true
}
}Synchronisation incrémentale
Pour ne récupérer que les biens modifiés depuis le dernier cycle, utilisez le filtre updated_since avec un timestamp ISO 8601. Combiné au curseur, cela permet une réconciliation incrémentale rapide.
Limites recommandées
- Limit par page : 20 à 100 (200 absolu).
- Au-delà, le serveur force à 100.
- Pour les exports complets, prévoir une boucle qui suit next_cursor.
- Throttler à 30 requêtes par minute en lecture si pagination complète.
Astuce
Pour un export complet de 10 000 biens, planifiez-le hors heures de pointe (nuit). Cela évite de saturer votre quota de rate limiting pendant la journée commerciale.
Tri et stabilité
Une pagination ne fonctionne que si l'ordre est stable. Ts-Immo trie par défaut par id croissant, garantissant qu'un bien créé pendant votre boucle de pagination apparaîtra à la fin, jamais au milieu rétroactivement.