API Pagination Nedir, Büyük Veri Aktarımlarında Nasıl Yönetilir?
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.

İÇİNDEKİLER
%0 okundu
- API Pagination (Sayfalama) Kavramı ve Temel İşlevi
- Büyük Veri Aktarımlarında API Pagination Neden Kritik Bir Gereksinimdir?
- Kurumsal Sistemlerde Yaygın API Pagination Yöntemleri
- Büyük Veri Yönetiminde Karşılaşılan Teknik Riskler ve Çözüm Yaklaşımları
- Büyük Ölçekli Veri Aktarımları İçin Mimari Uygulama Süreci
- API Pagination İçin En İyi Uygulamalar (Best Practices) ve Standartlar
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.
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:
Performans Düşüşü ($O(N)$ Maliyeti): Veritabanı
OFFSET 10000dendiğ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.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.comSunucu 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.
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:
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.
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.
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.
Hata Yakalama ve Rate Limit Optimizasyonu: @@CODE0@@ ve @@CODE1@@ yanıtlarını yakalayan dinamik throttling ve exponential backoff middleware bileşenleri entegre edilir.
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.
Büyük veri aktarımlarında güvenli sayfalama mimarisi kurulumu. Sıralama yapılacak alanlarda $O(\log N)$ erişim sağlayan bileşik indeksleri tanımlayın ve NULL değerleri engelleyin. İstemciye opak (opaque) imleçler dönen ve maksimum limit kısıtı içeren güvenli endpoint şablonunu oluşturun. İ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.Adım Adım Süreç
İndeks ve Veri Tabanı Katmanını Yapılandırın
Cursor Tabanlı API Sözleşmesini Tanımlayın
Checkpoint Mekanizması ile İstemci Tüketimini Başlatın
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: 154000Eğ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.
Büyük tablolarda @@CODE 0@@ sorgusu çalıştırmaktan kaçının ve @@CODE 1@@ boolean kontrolünü tercih edin.Total Count Optimizasyonu
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.