Sayfalama, filtreleme ve sıralama
Cursor tabanlı listeleme (limit, cursor, next_cursor, has_more), cursor biçimi ve geçerliliği, filter[...] ve sort parametreleri, SDK'larda tüm sayfaları dolaşma yardımcıları.
Liste uçları cursor tabanlıdır: sayfa numarası yoktur, her yanıt bir sonraki sayfanın imlecini verir. Bu yaklaşım büyük tablolarda tutarlı ve hızlıdır (yeni kayıt eklenmesi sayfaları kaydırmaz).
İstek
| Parametre | Açıklama |
|---|---|
limit | Sayfa boyutu; varsayılan 50, en fazla 200 |
cursor | Önceki yanıttaki next_cursor; ilk sayfada verilmez |
sort | Uca göre izin verilen alanlar; - öneki azalan (ör. sort=-created_at, kullanıcı listesinde last_active_at) |
filter[alan]=değer / uca özgü filtreler | Ör. GET /v1/notifications?status=completed&source=campaign, GET …/users?tag=plan:pro&last_active_after=2026-10-01T00:00:00Z, GET …/suppressions?channel=email&reason=bounce |
Yanıt
{
"data": [ { "id": "msg_01J…", "…": "…" } ],
"next_cursor": "eyJpZCI6Im1zZ18wMUouLi4ifQ",
"has_more": true
}has_more: falseise son sayfadasınız;next_cursornullolur.- Cursor, son kaydın kimliğini (ve varsa sıralama anahtarını) içeren base64url kodlu opak bir değerdir; içeriğine bağımlı kod yazmayın. Geçersiz ya da farklı sıralamayla üretilmiş cursor
400 HS_VALIDATION_ERROR(details.field: cursor) döner. - Cursor'ın süresi dolmaz; ancak aradaki silmeler nedeniyle sayfa boyutu
limit'ten küçük olabilir.
curl "https://api.pushizo.com/v1/apps/app_…/users?limit=100&sort=-last_active_at" -H "Authorization: Bearer $PUSHIZO_API_KEY"
curl "https://api.pushizo.com/v1/apps/app_…/users?limit=100&sort=-last_active_at&cursor=eyJpZCI6…" -H "Authorization: Bearer $PUSHIZO_API_KEY"SDK yardımcıları
Tüm sunucu SDK'ları sayfaları öğe öğe dolaşan yardımcılar sunar:
for await (const user of hs.paginate((cursor) => hs.users.list({ cursor, limit: 200 }))) {
// user
}Yardımcı, has_more yanlış olana kadar next_cursor ile devam eder; yeniden denemeler aynı cursor ile yapılır. Büyük toplu çıkarımlar için sayfalama yerine CSV dışa aktarma daha verimlidir.
Idempotency
Idempotency-Key başlığı ve idempotency_key alanı, 24 saatlik saklama, aynı/farklı gövde davranışı, sürmekte olan istek kirası, hangi işlemlerin desteklediği ve SDK'lardaki otomatik anahtar.
Sürümleme ve uyumluluk
/v1 uyumluluk sözü, geriye dönük uyumlu ekleme kuralları, kırıcı değişiklik politikası ve yeni sürüm yolu, kullanımdan kaldırma, OpenAPI/SDK sürümleri ve değişiklik günlüğü.