API Pagination Nedir, Büyük Veri Aktarımlarında Nasıl Yönetilir?

Yazar: Ahmet YılmazYayın: 26 Ağu 2026Güncelleme: 27 Ağu 202615 dk Okuma

API pagination, büyük veri setlerini küçük parçalara (sayfalara) bölerek aktarma yöntemidir. Sunucu yükünü azaltır, ağ performansını artırır ve bellek tüketimini optimize eder.

API Pagination Nedir, Büyük Veri Aktarımlarında Nasıl Yönetilir? için öne çıkan görsel
API Pagination Nedir, Büyük Veri Aktarımlarında Nasıl Yönetilir? için öne çıkan görsel

API pagination, büyük veri setlerini küçük parçalara (sayfalara) bölerek aktarma yöntemidir. Sunucu yükünü azaltır, ağ performansını artırır ve bellek tüketimini optimize eder.

Modern yazılım mimarilerinde ve kurumsal veri entegrasyonlarında veritabanı boyutları gigabaytlar hatta terabaytlar mertebesine ulaştığında, tek bir API çağrısı üzerinden yüz binlerce kaydı istemciye döndürmeye çalışmak ciddi performans darboğazlarına ve sistem çökmelerine yol açar. Geliştiriciler ve sistem mimarları için API Pagination Nedir, Büyük Veri Aktarımlarında Nasıl Yönetilir? sorusunun yanıtı; yalnızca veri parçalama tekniğini değil, veritabanı indeksleme stratejilerini, ağ bant genişliği yönetimini ve veri tutarlılığını kapsayan çok boyutlu bir optimizasyon sürecini ifade eder. Doğru kurgulanan bir sayfalama mimarisi, sunucu yanıt süresi ve bellek tüketimini dengede tutarak kesintisiz bir veri aktarım hattı kurmanızı sağlar.

API Pagination (Sayfalama) Kavramı ve Temel İşlevi

API pagination, istemci (client) ile sunucu (server) arasındaki HTTP protokolü üzerinden gerçekleşen veri transferlerinde, milyonlarca kayıttan oluşan devasa tabloları yönetilebilir küçük paketler (chunk/page) halinde sunmayı sağlayan bir endpoint tasarımı yaklaşımıdır. Bir RESTful API veya GraphQL servisinde sayfalama mekanizması bulunmadığında, istemcinin yaptığı standart bir GET /api/v1/orders isteği, veritabanındaki tüm sipariş tablosunun RAM'e yüklenmesine ve megabaytlarca JSON metninin tek bir HTTP response gövdesinde (payload) serialize edilmesine neden olur. Bu durum, istemci tarafında bellek sızıntısı (memory leak) riskini doğururken, sunucu tarafında CPU kullanımını tepe noktasına taşır.

Sayfalama mimarisinin birincil amacı, sunucu yanıt süresini (response time) deterministik ve düşük bir seviyede tutmaktır. İstemcinin ihtiyaç duyduğu veri miktarı kadar (@@CODE0@@ veya @@CODE1@@) veriyi sorgulamak, arka plandaki SQL veya NoSQL veritabanlarının gereksiz disk I/O yapmasını engeller. Sayfalama aynı zamanda ağ bant genişliği (network bandwidth) tüketimini düzenleyerek hem istemcinin mobil ya da web arayüzünde hızlı yanıt almasını sağlar hem de altyapı maliyetlerini doğrudan düşürür.

API Sayfalama Tanımı ve Amacı

Teknik bağlamda API sayfalama; bir veri koleksiyonunu belirli bir sıralama düzenine (order) göre parçalara ayıran, her parçaya bir tanımlayıcı (sayfa numarası, offset değeri, zaman damgası veya imleç token'ı) atayan ve istemcinin bu tanımlayıcıları kullanarak ardışık sorgular atmasını sağlayan bir durumsuz (stateless) gezinme protokolüdür. Sayfalama yapılmadığında ortaya çıkan JSON payload boyutu istemci tarayıcılarının parse kabiliyetini aşabilir ya da mobil uygulamaların işletim sistemi tarafından "yüksek bellek tüketimi" gerekçesiyle kapatılmasına (OOM - Out of Memory Crash) yol açabilir.

Kurumsal sistemlerde sayfalama; sadece kullanıcı arayüzlerindeki "1, 2, 3... Sonraki" butonlarını beslemekle kalmaz, aynı zamanda mikroservisler arası asenkron veri senkronizasyonunda, veri ambarı (ETL) aktarımlarında ve üçüncü parti entegrasyonlarda veri akış hızını kontrol altında tutan bir regülatör görevi üstlenir.

GET /api/v1/products?page=2&limit=50 HTTP/1.1
Host: api.kurum.com
Accept: application/json
{
  "data": [
    { "id": 101, "name": "Kurumsal Sunucu A", "price": 4200.00 },
    { "id": 102, "name": "Kurumsal Sunucu B", "price": 5100.00 }
  ],
  "meta": {
    "page": 2,
    "limit": 50,
    "total_records": 12500,
    "total_pages": 250
  },
  "links": {
    "self": "/api/v1/products?page=2&limit=50",
    "next": "/api/v1/products?page=3&limit=50",
    "prev": "/api/v1/products?page=1&limit=50"
  }
}

Tek Seferlik Büyük Veri Çağrısının Riskleri

Büyük hacimli veri setlerini tek seferde (unpaginated) çekmeye çalışmak, yazılım mimarilerinde domino etkisi yaratan teknik arızalara neden olur. Bu arızaların başında HTTP 504 Gateway Timeout ve HTTP 502 Bad Gateway hataları gelir. Bir veritabanı yüz binlerce satırı bir araya getirip diskten okurken geçen süre, ters vekil sunucuların (Reverse Proxy - Nginx, HAProxy, Cloudflare vb.) varsayılan zaman aşımı (timeout) sürelerini (genellikle 30-60 saniye) aşar ve bağlantı kopar.

Bunun yanı sıra veritabanı seviyesinde "Full Table Scan" (tam tablo taraması) tetiklenir. İndekslenmemiş veya filtrelenmemiş devasa sorgular, veritabanı belleğindeki önbellek havuzlarını (Buffer Pool) temizleyerek diğer eşzamanlı sorguların da yavaşlamasına yol açar. Sunucu katmanında ise çöp toplayıcı (Garbage Collector), devasa JSON nesnelerini bellekten temizlemeye çalışırken CPU'yu kilitler ve uygulama geçici olarak gelen isteklere yanıt veremez hale gelir.

Büyük Veri Aktarımlarında API Pagination Neden Kritik Bir Gereksinimdir?

Büyük veri aktarımlarında API pagination kullanımı, yalnızca bir kodlama tercihi değil, sistem stabilitesini ve ölçeklenebilirliğini doğrudan belirleyen mimari bir zorunluluktur. İki kurumsal sistem arasında günlük 10 milyon kayıt aktarılması gereken bir senaryoda, sayfalama stratejisi belirlenmeden kurgulanacak bir ETL (Extract, Transform, Load) boru hattı ilk birkaç bin işlem sonrasında tıkanacaktır. Veri aktarımını küçük ve doğrulanabilir dilimlere bölmek, başarısız olan isteklerin tüm süreci baştan başlatmak yerine sadece ilgili sayfadan itibaren yeniden denenmesine (retry mechanism) imkan tanır.

Kurumsal entegrasyonlarda sayfalama; API üreticisi (provider) ile tüketicisi (consumer) arasındaki sözleşmeyi (contract) güvence altına alır. Sayfalanmış endpoint'ler sayesinde sunucu sağlayıcısı, tek bir istemcinin tüm sistem kaynaklarını tüketmesini engeller. İstemci tarafı ise hafızasında küçük veri bloklarını işleyip diske yazarak sabit bir bellek ayak iziyle (constant memory footprint) operasyonu sürdürür.

Sunucu ve Ağ Performansına Etkileri

Büyük veri aktarımlarında ağ performansını belirleyen ana parametreler; iletilen veri paketi boyutu (MTU paket parçalanması), TCP el sıkışmaları ve serileştirme (serialization) maliyetleridir. 50 MB büyüklüğündeki tek bir JSON cevabını ağ üzerinden göndermek; paket kaybı (packet loss) durumunda tüm dosyanın yeniden iletilmesini gerektirirken, 500 KB'lık 100 sayfa halinde transfer etmek ağ kesintilerine karşı yüksek tolerans sağlar.

Sunucu yanıt süresi açısından bakıldığında, veritabanı motoru küçük veri setlerini B-Tree veya LSM indeksleri üzerinden mikro saniyeler içinde çekebilir. Sayfalama, disk I/O operasyonlarını zamana yayarak veritabanı kuyruğundaki (connection pool) kilitlenmeleri (lock contention) ortadan kaldırır. Bu durum, veri aktarımı devam ederken sistemin son kullanıcılara da hizmet vermeye devam etmesini mümkün kılar.

Bellek Tüketimi ve Kaynak Optimizasyonu

Bellek optimizasyonunda temel prensip, verinin üretildiği hız ile tüketildiği hız arasındaki dengedir. Sayfalamasız aktarımlarda veritabanı tüm satırları sunucunun RAM'ine yığar, sunucu bunu string formatına dönüştürür ve HTTP soketine yazar. Bu zincirde tek bir veri seti bellekte 3-4 kat fazla yer kaplayabilir (Object Overhead). 1 milyon kullanıcılık bir tablonun JSON karşılığı RAM'de yüzlerce megabaytlık anlık şişmelere yol açar.

API pagination, akış tabanlı (stream-like) bir döngü kurar. İstemci 1000 kaydı talep eder, işler, veritabanına yazar veya dosyaya kaydeder; ardından belleği boşaltarak bir sonraki 1000 kaydı ister. Bu sayede aktarılan toplam veri miktarı 500 GB olsa dahi uygulamanın kullandığı bellek miktarı hiçbir zaman 100 MB'ı aşmaz.

Performans KriteriSayfalamasız Tekil Çağrı (Unpaginated)Sayfalanmış Çağrı (Paginated - Batch 1K)
Bellek Tüketimi (RAM)Veri hacmiyle doğru orantılı artar ($O(N)$)Sabit ve kontrollü ($O(1)$)
Ağ Hata ToleransıDüşük (Bağlantı koptuğunda %0 başarı)Yüksek (Kopulan sayfadan devam edilebilir)
Sunucu Yanıt Süresi (TTFB)Yüksek ve tahmin edilemez (10-120+ sn)Düşük ve kararlı (50-200 ms)
Veritabanı KilitlenmesiYüksek disk I/O ve tablo kilit riskiDüşük I/O, indeks bazlı hızlı okuma
Rate Limit / Kota UyumuTek istekte yüksek kota harcar veya patlarİstek aralıkları ayarlanabilir (throttling)

Bellek Tüketimi (RAM)

Sayfalamasız Tekil Çağrı (Unpaginated)

Veri hacmiyle doğru orantılı artar ($O(N)$)

Sayfalanmış Çağrı (Paginated - Batch 1K)

Sabit ve kontrollü ($O(1)$)

Ağ Hata Toleransı

Sayfalamasız Tekil Çağrı (Unpaginated)

Düşük (Bağlantı koptuğunda %0 başarı)

Sayfalanmış Çağrı (Paginated - Batch 1K)

Yüksek (Kopulan sayfadan devam edilebilir)

Sunucu Yanıt Süresi (TTFB)

Sayfalamasız Tekil Çağrı (Unpaginated)

Yüksek ve tahmin edilemez (10-120+ sn)

Sayfalanmış Çağrı (Paginated - Batch 1K)

Düşük ve kararlı (50-200 ms)

Veritabanı Kilitlenmesi

Sayfalamasız Tekil Çağrı (Unpaginated)

Yüksek disk I/O ve tablo kilit riski

Sayfalanmış Çağrı (Paginated - Batch 1K)

Düşük I/O, indeks bazlı hızlı okuma

Rate Limit / Kota Uyumu

Sayfalamasız Tekil Çağrı (Unpaginated)

Tek istekte yüksek kota harcar veya patlar

Sayfalanmış Çağrı (Paginated - Batch 1K)

İstek aralıkları ayarlanabilir (throttling)

Kurumsal Sistemlerde Yaygın API Pagination Yöntemleri

API mimarisi tasarlarken tek bir evrensel sayfalama yöntemi bulunmaz; veri setinin büyüklüğü, verinin yazılma sıklığı, indeksleme yapısı ve istemcinin veriye erişim şekli (rastgele erişim veya ardışık akış) kullanılacak yöntemi belirler. Kurumsal ekosistemlerde temel olarak üç ana sayfalama yöntemi uygulanır: Offset/Limit, Keyset Pagination ve Cursor-Based Pagination.

Her yöntemin kendine özgü zaman karmaşıklığı ($O(N)$ vs $O(1)$), bellek maliyeti ve veri tutarlılığı dinamikleri vardır. Mimarların bu yöntemler arasındaki takasları (trade-offs) doğru analiz etmesi gerekir.

Offset ve Limit Tabanlı Sayfalama

Offset ve Limit, RESTful API'lerde en yaygın kullanılan ve uygulanması en basit olan sayfalama yaklaşımıdır. SQL sorgularındaki @@CODE0@@ ve @@CODE1@@ anahtar kelimelerine doğrudan karşılık gelir. İstemci kaç kayıt istediğini (@@CODE2@@) ve kaç kaydı atlamak istediğini (@@CODE3@@ veya page) parametre olarak gönderir.

-- Sayfa 1 (İlk 20 kayıt)
SELECT id, title, created_at FROM articles ORDER BY created_at DESC LIMIT 20 OFFSET 0;

-- Sayfa 500 (10.000 kayıt atla, sonraki 20 kaydı al)
SELECT id, title, created_at FROM articles ORDER BY created_at DESC LIMIT 20 OFFSET 10000;

Bu yöntemin en büyük avantajı, kullanıcının doğrudan belirli bir sayfaya atlamasına (/articles?page=15) ve arayüzde toplam sayfa sayısını göstermeye imkan tanımasıdır. Ancak büyük veri aktarımlarında iki kritik soruna yol açar:

  1. Performans Düşüşü ($O(N)$ Maliyeti): Veritabanı OFFSET 10000 dendiğinde, ilk 10.000 satırı diskten veya indeksten okur, bunları belleğe alır, 10.000 satırı çöpe atar ve sadece istenen 20 satırı döner. Offset değeri büyüdükçe sorgu süresi katlanarak artar.

  2. Kayıp/Mükerrer Kayıt Riski: İstemci 1. sayfayı okurken sisteme yeni bir kayıt eklenirse, tüm satırlar bir basamak aşağı kayar. İstemci 2. sayfaya geçtiğinde, 1. sayfada okuduğu son kaydı tekrar okur (duplication). Veri silinirse kayıtlar yukarı kayar ve bazı kayıtlar hiç okunmadan atlanır (data skipping).

Keyset (Anahtar Seti) Tabanlı Sayfalama

Keyset pagination, Offset yönteminin derin sayfalardaki performans sorununu çözmek için geliştirilmiştir. Bu yöntemde kayıt atlamak (@@CODE0@@) yerine, sıralı bir indeks sütunundaki son okunan değer bir filtreleme koşulu (@@CODE1@@) olarak kullanılır.

-- İlk Sayfa
SELECT id, title, created_at FROM articles 
ORDER BY id ASC LIMIT 20;

-- Sonraki Sayfa (Önceki sayfanın son id değeri: 1045)
SELECT id, title, created_at FROM articles 
WHERE id > 1045 
ORDER BY id ASC LIMIT 20;

Bu yaklaşım, veritabanının B-Tree indeksini doğrudan kullanarak istenen noktaya $O(\log N)$ sürede doğrudan atlamasını (seek operation) sağlar. Veritabanı önceki satırları taramak ve çöpe atmak zorunda kalmaz. Milyonlarca satırlık tablolarda dahi ilk sayfa ile 100.000'inci sayfa aynı sürede (genellikle birkaç milisaniye) yanıt verir.

Dezavantajı ise istemcinin rastgele bir sayfaya (örneğin doğrudan 45. sayfaya) atlayamamasıdır. Gezinme yalnızca "Sonraki" ve "Önceki" şeklinde ardışık yapılabilir. Ayrıca sıralama yapılan sütunun mutlaka sıralanabilir, tekil (veya bileşik tekil indeksle desteklenmiş) ve NULL içermeyen bir yapıda olması şarttır.

Cursor (İmleç) Tabanlı Sayfalama

Cursor-based pagination, Keyset yönteminin soyutlaştırılmış ve kurumsal API standartlarına (özellikle GraphQL ve modern REST API'ler) uyarlanmış en gelişmiş modelidir. İstemciye doğrudan veritabanı ID'si vermek yerine; sıralama kriterlerini, satır kimliğini ve gerekli metadata'yı içeren opak (opaque), genellikle Base64 ile encode edilmiş veya şifrelenmiş bir imleç (cursor) dizgisi iletilir.

İstemci bir sonraki sayfayı isterken bu imleci after parametresi olarak sunucuya gönderir:

GET /api/v1/events?limit=25&after=ZXllZE9yZGVyXzIwMjYtMDgtMjdfMTA0NQ== HTTP/1.1
Host: api.kurum.com

Sunucu bu imleci decode ettiğinde arka planda { "created_at": "2026-08-27T10:00:00Z", "id": 1045 } değerlerine ulaşır ve optimize edilmiş SQL sorgusunu çalıştırır:

SELECT id, event_type, created_at FROM events 
WHERE (created_at, id) < ('2026-08-27T10:00:00Z', 1045) 
ORDER BY created_at DESC, id DESC LIMIT 25;

Cursor mimarisi; gerçek zamanlı veri akışlarında, mobil sonsuz kaydırma (infinite scroll) ekranlarında ve büyük veri taşıma boru hatlarında tam veri tutarlılığı sunar. İstemci, veritabanının iç yapısını bilmek zorunda kalmaz ve API sağlayıcısı arkadaki sıralama algoritmasını istemciyi etkilemeden değiştirebilir.

Özellik / KriterOffset & LimitKeyset PaginationCursor-Based Pagination
Zaman Karmaşıklığı$O(N)$ (Derinleştikçe yavaşlar)$O(\log N)$ (Sabit hızlı)$O(\log N)$ (Sabit hızlı)
Rastgele Sayfaya AtlamaMümkün (page=12)Mümkün değilMümkün değil
Veri Değişimine DayanıklılıkZayıf (Kayıp/mükerrer kayıt)YüksekÇok Yüksek
Gerçek Zamanlı Veri UyumuUygun değilUygunTam uyumlu
İstemci KarmaşıklığıDüşükOrtaOrta
Uygulama AlanıYönetim panelleri, statik veriETL, raporlama, log aktarımıSosyal ağlar, akış verileri, GraphQL

Zaman Karmaşıklığı

Offset & Limit

$O(N)$ (Derinleştikçe yavaşlar)

Keyset Pagination

$O(\log N)$ (Sabit hızlı)

Cursor-Based Pagination

$O(\log N)$ (Sabit hızlı)

Rastgele Sayfaya Atlama

Offset & Limit

Mümkün (page=12)

Keyset Pagination

Mümkün değil

Cursor-Based Pagination

Mümkün değil

Veri Değişimine Dayanıklılık

Offset & Limit

Zayıf (Kayıp/mükerrer kayıt)

Keyset Pagination

Yüksek

Cursor-Based Pagination

Çok Yüksek

Gerçek Zamanlı Veri Uyumu

Offset & Limit

Uygun değil

Keyset Pagination

Uygun

Cursor-Based Pagination

Tam uyumlu

İstemci Karmaşıklığı

Offset & Limit

Düşük

Keyset Pagination

Orta

Cursor-Based Pagination

Orta

Uygulama Alanı

Offset & Limit

Yönetim panelleri, statik veri

Keyset Pagination

ETL, raporlama, log aktarımı

Cursor-Based Pagination

Sosyal ağlar, akış verileri, GraphQL

Büyük Veri Yönetiminde Karşılaşılan Teknik Riskler ve Çözüm Yaklaşımları

Büyük hacimli veri kümelerinin sistemler arasında taşınması sırasında karşılaşılan zorluklar sadece sorgu yazımından ibaret değildir. Milyonlarca satırlık aktarımlar saatler sürebilir ve bu süre zarfında kaynak veritabanında yeni kayıtlar oluşmaya, mevcut kayıtlar güncellenmeye veya silinmeye devam eder. Bu dinamik durum, sayfalama boru hatlarında sessiz veri bozulmalarına ve aktarım hatalarına neden olur.

Kurumsal seviyede bir veri entegrasyonu kurarken bu risklerin önceden öngörülmesi ve uygun yazılımsal bariyerlerin (circuit breaker, rate limiter, dead letter queue) mimariye dahil edilmesi gerekir.

Veri Tutarsızlığı ve Kayıp Kayıtlar (Data Drift Problemi)

Aktarım sürerken kaynak tablonun güncellenmesi "Data Drift" (Veri Kayması) sorununu doğurur. Özellikle Offset/Limit kullanılan senaryolarda aktarım başladıktan sonra tabloya eklenen tek bir satır, sonraki tüm sayfaların bir indeks geriye düşmesine ve aktarım sonucunda bazı verilerin mükerrer yazılmasına yol açar.

Bu riski bertaraf etmek için iki temel strateji uygulanır:

  • Snapshot / Transaction Isolation: Veritabanı destekliyorsa aktarım işlemi @@CODE0@@ veya @@CODE1@@ izolasyon seviyesinde başlatılan tek bir uzun ömürlü transaction üzerinden gerçekleştirilir (veya PostgreSQL'de @@CODE2@@ özelliği kullanılır). Ancak bu yöntem veritabanının @@CODE3@@ loglarını şişirebileceği için dikkatli yönetilmelidir.

  • Deterministic Tie-Breaking: Sıralama yapılan alanın (örneğin @@CODE0@@) tekil olmaması durumunda, aynı zaman damgasına sahip yüzlerce satır sayfa sınırlarına denk geldiğinde atlanabilir. Bu nedenle sorgu sıralamasına her zaman tekil bir ikincil alan (@@CODE1@@) eklenmelidir.

Veritabanı Sorgu Maliyeti, Indexleme ve Timeout Yönetimi

Sayfalanmış sorguların performansı tamamen doğru indeksleme stratejisine bağlıdır. @@CODE0@@ sorgusunun optimize çalışabilmesi için veritabanında @@CODE1@@ şeklinde bileşik indeks (composite index) tanımlanmalıdır. İndeks bulunmadığında veritabanı her sayfa için milyonlarca satırı diskten tarar ve sorgu zaman aşımına (query timeout) uğrar.

Uzun süren büyük veri aktarımlarında istemci tarafında akıllı zaman aşımı yönetimi kurgulanmalıdır. Ağ gecikmelerine karşı "Üstel Geri Çekilme" (Exponential Backoff) algoritması içeren otomatik yeniden deneme (retry) mekanizmaları devreye alınmalıdır.

// TypeScript / Node.js Örnek Exponential Backoff ile Güvenli Sayfa Çağrısı
async function fetchPageWithRetry(cursor: string | null, retries = 3, delay = 1000): Promise<ApiResponse> {
  try {
    const url = cursor ? `/api/v1/data?after=${cursor}&limit=500` : `/api/v1/data?limit=500`;
    const response = await httpClient.get(url, { timeout: 10000 });
    return response.data;
  } catch (error: any) {
    if (retries > 0 && (error.code === 'ECONNABORTED' || error.response?.status >= 500)) {
      console.warn(`Sorgu başarısız oldu. ${delay}ms sonra tekrar deneniyor... Kalan deneme: ${retries}`);
      await new Promise(resolve => setTimeout(resolve, delay));
      return fetchPageWithRetry(cursor, retries - 1, delay * 2);
    }
    throw error;
  }
}

API Hız Sınırları (Rate Limiting) ve Güvenlik Entegrasyonu

Kurumsal API'ler, sistem kaynaklarını korumak için Token Bucket veya Leaky Bucket algoritmalarıyla Hız Sınırlaması (Rate Limiting) uygular. Büyük veri aktarımı yapan bir istemci, sayfaları ardı ardına hiçbir bekleme süresi koymadan çağırırsa kısa sürede HTTP 429 Too Many Requests hatasıyla karşılaşır.

Sağlayıcı tarafından döndürülen HTTP başlıkları istemci tarafından dinamik olarak parse edilmelidir:

  • X-RateLimit-Limit: Belirli bir zaman penceresinde yapılabilecek maksimum istek sayısı.

  • X-RateLimit-Remaining: Mevcut pencerede kalan istek hakkı.

  • Retry-After: İstek hakkı bittiğinde istemcinin kaç saniye beklemesi gerektiğini belirten süre.

İstemci mimarisi, bu başlıkları okuyarak istek hızını otomatik olarak yavaşlatan bir akış kontrolcüsü (throttler) içermelidir.

Büyük Ölçekli Veri Aktarımları İçin Mimari Uygulama Süreci

Büyük ölçekli veri aktarımı gerektiren sistemlerde sayfalama altyapısını kurmak; yalnızca bir API endpoint'ine parametre eklemekten ibaret değildir. Süreç, veritabanı indeks modellemesinden istemci tarafındaki hata toleranslı veri tüketim döngülerine kadar uzanan metodolojik bir sıra izlemelidir.

Kurumsal bir veri aktarım boru hattının inşası aşağıdaki 5 kritik aşama üzerinden yapılandırılır:

  1. Veri Modeli ve İndeksleme Tasarımı: Sıralama ve sayfalama işlemlerinde kullanılacak alanlar belirlenir. Genellikle @@CODE0@@ veya monotonik artan bir @@CODE1@@ seçilir ve bu alanlara kapsayıcı indeksler (covering index) uygulanır.

  2. Endpoint ve Sözleşme Standardizasyonu: Cursor veya Keyset tabanlı sayfalama şeması belirlenir. Sayfa boyutu limitleri (örneğin varsayılan 100, maksimum 1000) sunucu seviyesinde sınırlandırılır.

  3. Akış ve Durum Yönetimi (State Persistence): Uzun süren aktarımlarda istemcinin son başarılı olduğu cursor değerini bir veritabanına veya Redis'e kaydetmesi (checkpointing) sağlanır. Bu, sistem çöktüğünde aktarımın sıfırdan değil, kalınan yerden devam etmesini sağlar.

  4. Hata Yakalama ve Rate Limit Optimizasyonu: @@CODE0@@ ve @@CODE1@@ yanıtlarını yakalayan dinamik throttling ve exponential backoff middleware bileşenleri entegre edilir.

  5. Yük ve Performans Testleri: Milyonlarca sentetik kayıt içeren veritabanı üzerinde derin sayfalama testleri yapılarak sorgu süreleri ve bellek profili doğrulanır.

SÜREÇ ADIMLARI

Adım Adım Süreç

Büyük veri aktarımlarında güvenli sayfalama mimarisi kurulumu.

01

İndeks ve Veri Tabanı Katmanını Yapılandırın

Sıralama yapılacak alanlarda $O(\log N)$ erişim sağlayan bileşik indeksleri tanımlayın ve NULL değerleri engelleyin.

02

Cursor Tabanlı API Sözleşmesini Tanımlayın

İstemciye opak (opaque) imleçler dönen ve maksimum limit kısıtı içeren güvenli endpoint şablonunu oluşturun.

03

Checkpoint Mekanizması ile İstemci Tüketimini Başlatın

İstemci tarafında her başarılı sayfa sonrasında cursor değerini saklayan ve kesintilerde kaldığı yerden devam eden aktarım döngüsünü kurun.

API Pagination İçin En İyi Uygulamalar (Best Practices) ve Standartlar

API tasarımı yaparken endüstri standartlarına sadık kalmak, hem sistemin bakımını kolaylaştırır hem de üçüncü parti geliştiricilerin servisinize hızla entegre olmasını sağlar. Sayfalama mekanizması tasarlanırken HTTP protokolünün sunduğu yerel yeteneklerden sonuna kadar faydalanılmalıdır.

REST mimarisinde en iyi uygulamalar, IETF RFC standartları ve GraphQL Connection Specification gibi global kabul görmüş spesifikasyonlar etrafında şekillenir.

Metadata ve HTTP Header Kullanım Standartları (RFC 5988 / 8288)

Sayfalama navigasyon bağlantılarını doğrudan JSON yanıt gövdesine (payload) gömmek yaygın bir pratik olsa da, REST mimarisinin saf prensiplerine göre bu bilgiler HTTP Link başlığı (RFC 8288) üzerinden taşınmalıdır. Bu yaklaşım, JSON gövdesini sadece saf iş verisine (business data) ayırarak payload boyutunu optimize eder.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.kurum.com/v1/users?after=cursor_next>; rel="next",
      <https://api.kurum.com/v1/users?before=cursor_prev>; rel="prev",
      <https://api.kurum.com/v1/users?after=cursor_last>; rel="last"
X-Total-Count: 154000

Eğer metadata JSON gövdesinde sunulacaksa, endüstri standardı olan JSON:API spesifikasyonuna sadık kalınmalıdır:

{
  "data": [
    { "type": "users", "id": "1001", "attributes": { "name": "Ahmet Yılmaz" } }
  ],
  "links": {
    "self": "https://api.kurum.com/v1/users?page[after]=cur_1001",
    "next": "https://api.kurum.com/v1/users?page[after]=cur_1050"
  },
  "meta": {
    "page_size": 50
  }
}

Kritik Uyarı (Total Count Maliyeti): Milyonlarca kayıt içeren büyük veri setlerinde @@CODE0@@ sorgusu çalıştırmak, tablonun büyüklüğüne bağlı olarak saniyeler sürebilir. İstemcinin zorunlu ihtiyacı yoksa yanıtta @@CODE1@@ veya @@CODE2@@ dönülmemeli; yalnızca "sonraki sayfa var mı?" (@@CODE3@@) bilgisi verilmelidir.

GraphQL Sayfalama ve Connection Modeli

GraphQL dünyasında sayfalama standartları, Relay projesi tarafından ortaya konan "GraphQL Cursor Connections Specification" ile belirlenmiştir. Bu modelde veriler @@CODE0@@, @@CODE1@@ ve pageInfo kavramları üzerinden hiyerarşik bir yapıda sunulur:

query GetUsersList($first: Int, $after: String) {
  users(first: $first, after: $after) {
    totalCount
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    edges {
      cursor
      node {
        id
        name
        email
      }
    }
  }
}

Bu yapı, istemciye her satırın kendi imlecine (@@CODE0@@) erişme esnekliği sunarken, sayfanın başlangıç ve bitiş imleçlerini (@@CODE1@@) doğrudan sağlayarak iki yönlü (bidirectional) veri akışını standartlaştırır.

KONTROL LİSTESİ

Total Count Optimizasyonu

Büyük tablolarda @@CODE

01

0@@ sorgusu çalıştırmaktan kaçının ve @@CODE

1@@ boolean kontrolünü tercih edin.

Sıkça Sorulan Sorular

Offset ve Cursor pagination arasındaki temel fark nedir?

Offset pagination sayfa numarası ve atlanacak kayıt sayısına göre çalışır, derin sayfalarda veritabanı tüm önceki satırları okuduğu için yavaşlar. Cursor pagination ise son okunan kaydın benzersiz belirtecini referans alarak doğrudan hedefe atlar, bu sayede veri büyüklüğünden bağımsız olarak sabit ve yüksek performans sunar.

Büyük veri setlerinde hangi sayfalama yöntemi performansı en çok artırır?

Büyük veri setlerinde ve ETL aktarımlarında Keyset veya Cursor-based pagination yöntemi performansı en üst seviyeye çıkarır. Bu yöntemler veritabanı indekslerini kullanarak doğrudan arama (index seek) yapar ve gereksiz satır taramalarını tamamen engeller.

REST API'lerde sayfalama yaparken toplam kayıt sayısı (Total Count) verilmeli mi?

Milyonlarca satırlık tablolarda toplam kayıt sayısını hesaplamak için @@CODE 0@@ çalıştırmak ciddi bir veritabanı yükü ve gecikme yaratır. Yüksek performans gerektiren büyük veri senaryolarında toplam sayı yerine yalnızca "sonraki sayfa mevcut mu" (@@CODE 1@@) bilgisinin dönülmesi tavsiye edilir.

Sayfalama sırasında veri tabanına yeni kayıt eklenirse ne olur?

Offset tabanlı sayfalamada araya yeni kayıt girmesi durumunda alt sayfalardaki veriler aşağı kayar ve istemci aynı kaydı mükerrer olarak okuyabilir. Cursor tabanlı sayfalamada ise sorgu son okunan kaydın değerine göre filtrelendiği için yeni eklemeler mevcut aktarım akışını bozmaz.

Keyset pagination hangi durumlarda kullanılamaz?

Sıralama yapılacak sütunda NULL değerler varsa veya sütundaki değerler benzersiz (unique) değilse tek başına kullanılamaz. Ayrıca kullanıcının doğrudan belirli bir sayfa numarasına (örneğin 15. sayfaya) atlamasının gerektiği arayüz senaryolarında Keyset yöntemi uygun değildir.

Büyük veri aktarımında HTTP 429 Too Many Requests hatası nasıl yönetilmelidir?

İstemci, sunucudan dönen Retry-After HTTP başlığını okumalı ve bu süre boyunca yeni istek göndermeyi durdurmalıdır. Başlık bulunmuyorsa, her başarısız istekten sonra bekleme süresini katlayarak artıran "Üstel Geri Çekilme" (Exponential Backoff) algoritması uygulanmalıdır.

API sayfalama için önerilen maksimum sayfa boyutu (limit) ne olmalıdır?

Kurumsal REST API standartlarında varsayılan sayfa boyutu genellikle 20 ile 50 kayıt arasında tutulur. Büyük veri aktarımları ve toplu veri çekme (bulk export) senaryolarında ise sunucu bellek kapasitesine ve satır genişliğine bağlı olarak maksimum üst sınır 500 veya 1000 kayıt olarak sınırlandırılmalıdır.

GraphQL API'lerde sayfalama standardı nasıl uygulanır?

GraphQL mimarisinde Relay Cursor Connections spesifikasyonu endüstri standardı olarak kabul edilir. Bu standartta sorgular @@CODE 0@@, @@CODE 1@@ ve sayfa navigasyon durumunu belirten @@CODE 2@@ (@@CODE 3@@, endCursor ) nesneleri üzerinden imleç tabanlı olarak yapılandırılır.

Son Adım

Dijital projenizi bugün planlayalım

Web, yazılım, e-ticaret, mobil uygulama, entegrasyon, SEO veya GEO ihtiyacınızı net bir kapsama dönüştürelim.