Sayfalama (pagination), bir REST API'nin büyük veri kümelerini istemciye parça parça sunmasını sağlar. Yanlış uygulandığında performans düşer, kullanıcı deneyimi bozulur ve hata ayıklama zorlaşır. Bu yazıda, REST API'lerde sayfalama için pratik ipuçlarını ve kontrol listesini bulacaksınız.
Sayfalama Yöntemleri
Üç temel sayfalama yaklaşımı vardır: offset/limit, cursor tabanlı ve keyset sayfalama. Her birinin güçlü ve zayıf yönleri farklıdır.
1. Offset/Limit Tabanlı Sayfalama
En yaygın yöntemdir. İstemci offset (kaç kayıt atlanacağı) ve limit (kaç kayıt döndürüleceği) parametrelerini gönderir. Örnek: GET /items?offset=20&limit=10. Bu yaklaşım implementasyonu kolaydır ancak veri seti büyüdükçe performans düşer; çünkü veritabanı tüm atlanan satırları saymak zorunda kalır. Ayrıca yeni eklenen veya silinen kayıtlar tutarsız sonuçlara yol açabilir.
2. Cursor Tabanlı Sayfalama
Bir imleç (cursor) kullanarak sonraki sayfayı işaret eder. İmleç genellikle benzersiz bir alanın (ör. id) kodlanmış halidir. Örnek: GET /items?cursor=abc123&limit=10. Bu yöntem büyük veri kümelerinde daha hızlıdır ve veri değişikliklerine karşı dayanıklıdır. Dezavantajı, toplam sayfa sayısını hesaplamanın zor olmasıdır.
3. Keyset Sayfalama
Seek-pagination olarak da bilinir. Son kaydın anahtar alanını kullanarak bir sonraki sayfayı getirir. Örnek: GET /items?after_id=100&limit=10. Performansı cursor tabanlıya benzer, ancak sıralama anahtarı üzerinde titiz olunmalıdır. Karmaşık filtrelerle kullanımı zordur.
Pratik İpuçları
- Maksimum limit belirleyin: İstemcinin isteyebileceği maksimum kayıt sayısını sınırlayın. Örneğin,
max_limit=100koyun. Aşan istekleri 400 Bad Request ile reddedin. - Toplam kayıt sayısını döndürmeyi düşünün: İstemciler genellikle toplam sayfa sayısını bilmek ister. Ancak bu, performans maliyeti getirebilir. Büyük veri kümelerinde toplam sayıyı tahmin etmek veya yalnızca ilk sayfada göstermek iyi bir uygulamadır.
- Link header kullanın (RFC 5988): REST standartlarına uygun olarak HTTP yanıt başlığında
Link: <https://api.example.com/items?cursor=xyz>; rel="next"gibi bağlantılar sağlayın. Bu, istemcinin manuel URL oluşturmasını engeller. - Tutarlı sıralama kullanın: Sayfalama, sıralama düzenine bağlıdır. Her istekte aynı
sortparametresinin geçerli olduğundan emin olun. Sıralamada boşluklar veya tekil olmayan değerler tutarsızlığa neden olur. - Hızlı Geri Bildirim: Geçersiz sayfa veya cursor isteklerine anlamlı hata mesajları dönün. Bu konuda REST API'lerde Standart Hata Kodları ve Anlamlı Hata Mesajları yazımızda detaylı bilgi bulabilirsiniz.
- Performans testi yapın: Seçtiğiniz sayfalama yöntemini beklenen veri hacminde test edin. Özellikle büyük tablolarda offset/limit yavaş çalışabilir. Cursor veya keyset daha iyi alternatifler sunar.
- Cache uyumlu tasarlayın: Sayfalanmış yanıtların önbelleğe alınması performansı artırır. API Caching Stratejileri yazımızda HTTP önbellekleme ipuçlarını bulabilirsiniz.
- API sürümünde değişiklikler: Sayfalama davranışını değiştirdiğinizde API versiyonlamayı düşünün. API Versiyonlama Stratejileri rehberimiz size yol gösterecektir.
Kontrol Listesi
Aşağıdaki kontrol listesini sayfalama implementasyonunuzda kullanabilirsiniz:
- İstemci tarafından gönderilen limit değeri belirlenen maksimumu aşıyorsa 400 dönülüyor mu?
- Offset/limit kullanılıyorsa, toplam sayı COUNT sorgusu optimize edildi mi?
- Cursor tabanlı ise, cursor geçerli bir kaydı işaret etmiyorsa 404 dönülüyor mu?
- Yanıtta
Linkheader ilefirst,last,next,prevbağlantıları sağlanıyor mu? - Sıralama alanı tekil (unique) ve sıralı mı? (Örn. id, timestamp)
- Büyük veri setlerinde cursor veya keyset yöntemi kullanılıyor mu?
- Veri değişikliklerinde sayfalama tutarlılığı kontrol edildi mi?
- Önbellekleme stratejisi (Cache-Control, ETag) uygulanıyor mu?
- Dokümantasyonda tüm sayfalama parametreleri açıklanmış mı?
Sık Yapılan Hatalar
- Büyük offset değerleri: Offset 10000 gibi değerler veritabanında ağır sorgulara yol açar. Bunun yerine cursor kullanın.
- Toplam sayıyı her istekte hesaplamak: COUNT(*) büyük tablolarda pahalıdır. Toplamı önbelleğe alın veya yalnızca ilk sayfada döndürün.
- Varsayılan limit belirlememek: İstemci limit belirtmezse çok fazla kayıt dönmekten kaçının. Örneğin varsayılan 10 kullanın.
- Tutarsız sıralama: Sıralama alanı olarak değişken (örn. isim) kullanılıyorsa, sayfalar arasında kayıt atlama veya tekrarlama olabilir.
Sonuç
Doğru sayfalama stratejisi, API performansını ve kullanıcı deneyimini doğrudan etkiler. Offset/limit küçük veriler için yeterli olsa da, ölçeklenebilir çözümler için cursor tabanlı yaklaşım önerilir. Kontrol listemizi kullanarak sayfalama implementasyonunuzu gözden geçirin ve hata ayıklama sürecinizi hızlandırın.
Sık Sorulan Sorular
REST API'de offset/limit mi yoksa cursor mu kullanmalıyım?
Küçük ve stabil veri setlerinde offset/limit basit ve yeterlidir. Büyük, sık değişen verilerde ve yüksek performans gereksinimlerinde cursor tabanlı sayfalama daha iyidir.
Sayfalama yanıtında toplam kayıt sayısını döndürmeli miyim?
İstemciler için yararlıdır ancak büyük verilerde performans maliyeti vardır. İlk sayfada toplamı döndürmek veya tahmini bir değer vermek iyi bir uzlaşmadır.
Sayfalama için Link header zorunlu mu?
Zorunlu değildir ancak REST standartlarına uygunluk ve istemci kolaylığı açısından önerilir. JSON yanıtında da linkler sunabilirsiniz.
Cursor tabanlı sayfalama nasıl çalışır?
Her yanıtta bir cursor (genellikle son kaydın ID'sinin kodlanmış hali) döndürülür. İstemci bir sonraki sayfayı almak için bu cursor'u parametre olarak gönderir.
Keyset sayfalama ile cursor arasındaki fark nedir?
Keyset sayfalama, sıralama anahtarını doğrudan kullanır (ör. after_id). Cursor tabanlı ise genellikle bir token olarak uygulanır ve daha esnektir.
