REST API tasarlarken veri listelerini sayfalama, büyük veri kümelerinde performans ve kullanıcı deneyimi için kritik bir karardır. İki yaygın yöntem olan offset tabanlı (limit/offset) ve cursor tabanlı sayfalama arasında seçim yapmak, API'nizin ölçeklenebilirliğini, tutarlılığını ve istemci tarafındaki karmaşıklığını doğrudan etkiler. Hangi yaklaşımın projenize uygun olduğunu belirlemek için her iki yöntemin artılarını, eksilerini ve uygun senaryolarını detaylıca inceleyelim.
Offset Tabanlı Sayfalama Nedir ve Nasıl Çalışır?
Offset tabanlı sayfalama, geleneksel LIMIT ve OFFSET SQL ifadelerine dayanır. İstemci, isteğe limit (sayfa başına kayıt sayısı) ve offset (atlanacak kayıt sayısı) parametrelerini ekler. Örneğin, GET /products?limit=10&offset=20 21. kayıttan itibaren 10 ürün döndürür. Bu yöntem basit, anlaşılır ve uygulaması kolaydır. Ancak büyük offset değerlerinde veritabanı performansı düşer çünkü sorgu, atlanan kayıtları yine de taramak zorundadır.
Cursor Tabanlı Sayfalama Nedir ve Nasıl Çalışır?
Cursor tabanlı sayfalama (keyset pagination), bir sonraki sayfanın başlangıç noktasını belirten benzersiz bir işaretçi (cursor) kullanır. Genellikle sıralı bir sütuna (örneğin, oluşturulma zamanı, ID) dayanır. İstemci, bir önceki sayfanın son kaydının referansını içeren bir cursor parametresi gönderir. Örnek: GET /products?limit=10&cursor=eyJpZCI6MjB9. Bu yöntem, offset'ten farklı olarak, atlanan kayıtları taramaz; doğrudan cursor değerinden başlayarak sorguyu yürütür, bu da sabit ve öngörülebilir bir performans sağlar.
Önemli Not: Büyük veri kümelerinde (milyonlarca kayıt) ve canlı veri senaryolarında cursor tabanlı sayfalama, offset tabanlıya göre önemli ölçüde daha hızlı ve tutarlıdır. Ancak, istemci tarafında daha karmaşık bir mantık gerektirir.
Performans Karşılaştırması
Offset tabanlı sayfalamada, OFFSET 10000 gibi bir değer, veritabanının 10.000 kaydı taramasına ve atmasına neden olur. Bu, özellikle büyük tablolarda ciddi gecikmelere yol açar. Cursor tabanlı yaklaşımda ise sorgu, indekslenmiş bir sütun üzerinde doğrudan arama yapar; her sayfa aynı hızda döner. Örneğin, WHERE created_at > '2026-06-01 00:00:00' gibi bir koşul indeks kullanır ve sayfa derinliğinden etkilenmez.
Tutarlılık ve Veri Bütünlüğü
Canlı sistemlerde offset tabanlı sayfalama, kullanıcı sayfalar arasında gezinirken yeni kayıt eklenmesi veya silinmesi durumunda kayma (drift) sorununa yol açar. Örneğin, kullanıcı sayfa 2'deyken yeni bir kayıt eklenirse, sayfa 3'te bir kayıt atlanabilir veya tekrarlanabilir. Cursor tabanlı sayfalama bu sorunu ortadan kaldırır çünkü her sayfa, bir önceki sayfanın son kaydına göre tanımlanır; araya giren kayıtlar sonraki sayfaları etkilemez.
Kullanım Durumları ve Seçim Kriterleri
Offset Tabanlı Ne Zaman Kullanılır?
- Veri kümesi küçük (birkaç yüz kayıt) ve sayfa sayısı sınırlıysa.
- Sayfa numaralarına doğrudan erişim (örneğin, kullanıcı sayfa 5'e gitmek istediğinde) gerekiyorsa.
- Veri nadiren değişiyorsa veya değişimin etkisi tolere edilebilir düzeydeyse.
Cursor Tabanlı Ne Zaman Kullanılır?
- Büyük veri kümeleri (milyonlarca kayıt) ve sınırsız kaydırma (infinite scroll) gerektiğinde.
- Gerçek zamanlı veri akışı veya sık güncellenen listelerde (örneğin, sosyal medya akışı, canlı yayın yorumları).
- Performans kritik öneme sahipse ve her sayfanın aynı hızda dönmesi isteniyorsa.
Uygulama Örnekleri ve İpuçları
Bir REST API'de cursor tabanlı sayfalama uygularken şu noktalara dikkat edin:
- Cursor'ı güvenli kodlayın: Cursor değerini base64 veya benzeri bir şekilde kodlayarak istemciye gönderin. Açık veri tabanı değerlerini doğrudan kullanmayın.
- İndeks kullanın: Cursor sütununun indekslenmiş olduğundan emin olun. Genellikle
idveyacreated_attercih edilir. - İleri ve geri sayfalama desteği: Bazı cursor tasarımları hem ileri hem geri sayfalama için iki cursor döndürür (örneğin,
next_cursorveprev_cursor). - Önbellek stratejileri: Sık erişilen sayfalar için sunucu tarafında önbellekleme düşünün. Örneğin, Redis ile cursor sonuçlarını geçici olarak saklayabilirsiniz.
Sonuç
Offset ve cursor tabanlı sayfalama arasında seçim yaparken projenizin ölçeğini, veri değişim sıklığını ve kullanıcı deneyimi gereksinimlerini değerlendirin. Küçük ve statik veri kümeleri için offset basit ve yeterli olabilirken, büyük ve dinamik sistemlerde cursor performans ve tutarlılık açısından üstün gelir. Modern web uygulamalarında, özellikle Next.js gibi sunucu tarafı render çözümleri ile birleştiğinde cursor tabanlı yaklaşım daha yaygın hale gelmektedir. Ayrıca, mikro ön yüz mimarilerinde farklı servislerin sayfalama yöntemlerini standartlaştırmak da önemlidir.
İster offset ister cursor kullanın, API belgelerinizde sayfalama mekanizmasını açıkça tanımlamayı unutmayın. İstemci geliştiricilerin doğru entegrasyon yapabilmesi için parametreler, yanıt formatı ve hata durumları net olmalıdır.
Sık Sorulan Sorular
Cursor tabanlı sayfalama ile offset tabanlı sayfalama arasındaki temel fark nedir?
Offset tabanlı sayfalama, atlanacak kayıt sayısını belirtir ve büyük offset değerlerinde performans düşer. Cursor tabanlı sayfalama ise bir sonraki sayfanın başlangıç noktasını belirten bir işaretçi kullanır; performansı veri büyüklüğünden bağımsızdır ve canlı veri senaryolarında tutarlılık sağlar.
Hangi durumlarda offset tabanlı sayfalama tercih edilmelidir?
Küçük veri kümelerinde (birkaç yüz kayıt) ve kullanıcıların belirli sayfa numaralarına doğrudan erişmesi gerektiğinde offset tabanlı sayfalama daha basit ve yeterlidir.
Cursor tabanlı sayfalama uygularken nelere dikkat edilmelidir?
Cursor değeri mutlaka güvenli bir şekilde kodlanmalı (örneğin base64), indekslenmiş bir sütun kullanılmalı ve geri sayfalama için çift yönlü cursor desteği sağlanmalıdır.
Büyük veri kümelerinde sayfalama performansını nasıl en iyi hale getirebilirim?
Cursor tabanlı sayfalama kullanarak, indekslenmiş bir sütun üzerinde sorgulama yapabilir ve veritabanı tarama yükünü azaltabilirsiniz. Ayrıca sunucu tarafında önbellekleme (Redis benzeri) ile sık erişilen sayfaları hızlandırabilirsiniz.
