Temeller

Sayfalama

İmzalı imleç (cursor) tabanlı sayfalama — neden offset yok, imleç nasıl taşınır, sınırlar ne.

Liste uçları imleç (cursor) tabanlı sayfalar. page=3 gibi bir offset parametresi yoktur ve bilinçli olarak yoktur.

Neden offset değil

Offset sayfalama iki yerde bozulur ve ikisi de sessizdir:

  1. Kayan liste. Sen 2. sayfayı okurken yeni bir kayıt eklenirse tüm kayıtlar bir sıra kayar; 3. sayfada bir kaydı iki kez görürsün ya da bir kaydı hiç görmezsin.
  2. Derin sayfa maliyeti. OFFSET 50000 veritabanına 50.000 satırı okuyup atmasını söyler; 40. sayfa 1. sayfadan kat kat pahalıdır.

İmleç, "en son gördüğün kaydın konumu"nu taşır: liste kaysa da senin okuma noktan sabit kalır.

Kullanımı

bash
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts?per_page=50" \
  -H "Authorization: Bearer blsk_..."
json
{
  "type": "list",
  "data": [ … ],
  "pages": {
    "type": "pages",
    "per_page": 50,
    "next": { "starting_after": "eyJjIjoxNzY0…" }
  }
}

Sonraki sayfa:

bash
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts?per_page=50&starting_after=eyJjIjoxNzY0…" \
  -H "Authorization: Bearer blsk_..."

pages.next yoksa liste bitmiştir. Bu tek durak koşuludur — boş data dizisini beklemek gereksiz bir tur daha attırır.

İmleç OPAKTIR

starting_after değeri HMAC ile imzalıdır ve içeriğini ayrıştırmamalısın:

  • Değeri değiştirirsen imza tutmaz ve 400 alırsın.
  • Biçimi haber vermeden değişebilir; ayrıştıran bir istemci bir gün kırılır.
  • İçinde çalışma alanı kimliği yoktur — kapsam her zaman anahtardan gelir, yani imleci taklit ederek başka bir kiracının verisine ulaşmak imkânsızdır.

Yapman gereken tek şey: aldığın değeri aynen geri göndermek.

Sınırlar

ParametreVarsayılanEn fazla
per_page50150

Aşarsan 400 ve parameter_invalid alırsın.

Sıralama

Liste uçları (created_at DESC, id DESC) sıralıdır. id bir eşitlik bozucudur: aynı mikrosaniyede oluşmuş iki kayıt olsa bile sıra kararlıdır ve sayfalar arasında kayma olmaz.

Tüm listeyi çekiyorsan per_page=150 kullan ve pages.next boşalana kadar döngü kur. Her turda hız sınırını gözet — X-RateLimit-Remaining başlığı kaç isteğin kaldığını söyler.