REST API'ler büyük veri kümelerini döndürürken, tüm kayıtları tek seferde göndermek hem sunucu hem de istemci için ağır bir yük oluşturur. Bu noktada pagination (sayfalama), filtering (filtreleme) ve sorting (sıralama) mekanizmaları, API'nizin performansını ve kullanılabilirliğini doğrudan etkiler. Peki bu üç özelliği REST prensiplerine uygun, güvenli ve ölçeklenebilir şekilde nasıl tasarlamalısınız?
Neden Pagination, Filtering ve Sorting Olmazsa Olmaz?
Bir API endpoint'i binlerce kayıt döndürdüğünde yanıt süresi artar, ağ bant genişliği tükenir ve istemci tarafında bellek taşması yaşanabilir. Sayfalama sayesinde veri parçalara ayrılır; filtreleme gereksiz verileri elemine eder; sıralama ise kullanıcının ihtiyacına göre düzenli bir liste sunar. Anlamlı HTTP durum kodları ile birleştiğinde, bu mekanizmalar API'nizin profesyonelliğini ortaya koyar.
Pagination Stratejileri: Offset vs Cursor-Based
Sayfalama için yaygın iki yaklaşım bulunur: offset-based ve cursor-based (keyset pagination). Her birinin avantajları ve kullanım senaryoları farklıdır.
Offset-Based Pagination
Klasik limit ve offset parametreleri ile çalışır. Örneğin GET /items?limit=20&offset=40 41. kayıttan itibaren 20 kayıt getirir. Kolay uygulanabilir olmasına rağmen, büyük offset değerlerinde performans düşer (veritabanı tüm satırları tarar) ve sayfalanan veriye ekleme/silme yapıldığında kaymalar oluşur.
Cursor-Based Pagination
Bir imleç (cursor) kullanarak son kaydın benzersiz bir alanına (genellikle id veya zaman damgası) göre sayfalama yapar. Örneğin GET /items?limit=20&cursor=eyJpZCI6MTAwfQ. Bu yöntem, veritabanında indeks kullanarak hızlı çalışır ve veri tutarlılığını korur.
Yüksek trafikli ve sık veri ekleme/silme yapılan uygulamalarda cursor-based pagination kullanmak, sayfalar arasında veri kaymasını önler ve tutarlı bir kullanıcı deneyimi sağlar.
Aşağıdaki tabloda iki yöntemin karşılaştırmasını bulabilirsiniz:
| Özellik | Offset-Based | Cursor-Based |
|---|---|---|
| Performans (büyük veri) | Düşük (tüm tabloyu tarar) | Yüksek (indeks kullanır) |
| Veri tutarlılığı | Düşük (sayfalar arasında kayma) | Yüksek (son durumu yansıtır) |
| Karmaşıklık | Düşük | Orta (cursor oluşturma ve çözme) |
| Rastgele sayfa atlama | Kolay (offset değiştir) | Zor (cursor bilinmeli) |
Çoğu modern API, cursor-based yaklaşımı tercih eder. Ancak admin panelleri gibi rastgele sayfa atlamanın önemli olduğu durumlarda offset-based kullanılabilir. API versiyonlama yaparken bu seçimi belgelemeyi unutmayın.
Filtering: Kullanıcıya Özelleştirilmiş Veri
Filtreleme, istemcinin yalnızca ihtiyaç duyduğu kayıtları almasını sağlar. En yaygın yöntem query string parametreleridir. Örneğin GET /items?category=electronics&price_min=100&price_max=500.
Filtreleme İçin En İyi Uygulamalar
- Query string kullanın: Filtre parametrelerini URL'nin sorgu kısmında taşıyın. Kaynak adında filtreleme yapmaktan kaçının.
- Operatör desteği:
eq,gt,lt,ingibi operatörleri bir sözleşme (örn. OData veya JSON:API) ile sunun. - Güvenlik: Filtre alanlarını beyaz listeye alın. Doğrudan SQL sorgusuna enjekte edilebilecek parametreleri asla kabul etmeyin.
- Büyük/küçük harf duyarlılığı: Tüm filtrelemeleri case-insensitive yaparak kullanıcı hatasını azaltın.
Sorting: Birden Çok Alanda Sıralama
Sıralama genellikle sort parametresi ile yapılır. Örneğin GET /items?sort=price:asc,created_at:desc. Aşağıdaki noktalara dikkat edin:
- Alan doğrulaması: Yalnızca izin verilen alanlarda sıralamaya izin verin. Aksi halde istenmeyen veri sızıntısı olabilir.
- Varsayılan sıralama:
sortparametresi gelmezse anlamlı bir varsayılan (örn.created_at:desc) kullanın. - Birden çok alan: Virgülle ayrılmış alanları destekleyerek karmaşık sıralamalara izin verin.
Sık Yapılan Hatalar ve Dikkat Edilmesi Gerekenler
- Limitsiz sayfalama: Maksimum limit değeri belirleyin (örn. 100). Aksi halde tüm veri seti çekilebilir.
- Offset ile büyük veri: Offset-based kullanıyorsanız, büyük offset'lerde performans sorunu yaşayacağınızı unutmayın.
- Filtrelemede SQL enjeksiyonu: Kullanıcı girdisini doğrudan veritabanı sorgusuna eklemeyin. ORM kullanıyorsanız bile parametrize edilmiş sorgular tercih edin.
- Sorting alanı ifşası: Hassas alanlarda (parola, e-posta gibi) sıralamaya izin vermeyin.
Bu en iyi uygulamalar, API'nizin hem güvenli hem de yüksek performanslı olmasını sağlar. Rate limiting gibi diğer mekanizmalarla entegre ederek API'nizi daha da sağlamlaştırabilirsiniz. Ayrıca hata yönetimi ile birlikte eksiksiz bir API tasarımı oluşturabilirsiniz.
Unutmayın: İyi tasarlanmış bir API, kullanıcıların veriye hızlı ve güvenli erişmesini sağlarken sunucu kaynaklarını da verimli kullanır. Pagination, filtering ve sorting bu denklemin temel taşlarıdır.
Sık Sorulan Sorular
Offset-based pagination neden performans sorunu yaratır?
Offset-based pagination, büyük offset değerlerinde veritabanının tüm satırları taramasına neden olur. Örneğin offset=10000, limit=20 için veritabanı 10020 satır okur ve 20'sini döndürür. Bu durum sorgu süresini artırır.
Cursor-based pagination nasıl çalışır?
Cursor-based pagination, son kaydın benzersiz bir alanını (genellikle id veya timestamp) imleç olarak kullanır. İstemci sonraki sayfayı almak için bu imleci gönderir. Veritabanı imleçten sonraki kayıtları indeks üzerinden hızlıca getirir.
Filtreleme parametrelerini güvenli hale getirmek için ne yapmalıyım?
Filtrelenebilecek alanları beyaz listeye alın ve kullanıcı girdisini doğrudan sorguya eklemeyin. Parametrize edilmiş sorgular veya ORM kullanarak SQL enjeksiyon riskini ortadan kaldırın.
Birden çok alanda sıralama nasıl desteklenir?
Genellikle 'sort' parametresi ile virgülle ayrılmış alan:yön çiftleri kullanılır. Örneğin 'sort=price:asc,created_at:desc'. Sunucu bu alanları ayrıştırarak sıralama sorgusuna uygular.
