Bir collection endpoint'i için sayfalama, filtreleme ve sıralamayı nasıl tasarlarsınız?

Question

IT Interview Practice · Accepted Answer

Bir collection döndüren herhangi bir endpoint'in sonuçları **sınırlaması ve şekillendirmesi** gerekir. Üç mesele — sayfalama, filtreleme, sıralama — hepsi query string'de yaşar.

## Sayfalama: offset vs cursor

**Offset (sayfa tabanlı)** — `?page=3&limit=20` ya da `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Basit ve herhangi bir sayfaya atlamaya izin verir, ama ölçekte iki sorunu var: `OFFSET 100000`, veritabanını 100 bin satırı tarayıp atmaya zorlar (yavaş) ve istekler arasında satır eklenir/silinirse öğeler **kayar** ve yinelenenler ya da atlamalar görürsünüz.

**Cursor (keyset)** — client, görülen son öğeye opak (opaque) bir pointer geçirir.
```http
GET /orders?limit=20&cursor=eyJpZCI6MTAyMH0 HTTP/1.1
```
```http
HTTP/1.1 200 OK

{
  "data": [ /* 20 orders */ ],
  "page": { "next_cursor": "eyJpZCI6MTA0MH0", "has_more": true }
}
```
Server, cursor'ı `WHERE id > 1020 ORDER BY id LIMIT 20`'ye çevirir — herhangi bir derinlikte hızlı kalan ve eklemelere karşı **kararlı** olan, index kullanan bir arama. Ödünleşim: "sayfa 500"e rastgele erişim yok.

```text
Offset  → small datasets, admin UIs, "jump to page N"
Cursor  → large/infinite feeds, real-time data, mobile scroll
```

## Filtreleme ve sıralama

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtreleyin**: field=value query param'larıyla (`status=shipped`). İzin verilen alanları whitelist'leyin.
- **Sıralayın**: bir `sort` param'ıyla; `-` öneki azalan demektir (`-created_at`). Kararlı sıralama için çoklu anahtarı destekleyin.
- Her zaman **`limit`'i sınırlayın** (ör. en çok 100), böylece bir client bir milyon satır isteyemez.

## Neden önemli

Bu, en pratik API tasarım sorularından biridir; çünkü neredeyse her liste endpoint'i onunla karşılaşır ve seçimin gerçek performans sonuçları vardır. Mülakatçı genellikle **offset-vs-cursor ödünleşimini** yoklar: her yerde offset sayfalamaya sarılan bir aday, tabloyu tarayan `OFFSET 1000000`'ın acısını ya da bir kullanıcının sonsuz bir feed'i kaydırırken yeni bir tane eklendiği için aynı gönderiyi iki kez gördüğü "kayan sonuçlar" bug'ını hiç yaşamamıştır. Cursor sayfalama, sorguyu index kullanan bir keyset aramasına dönüştürerek her ikisini de çözer; her büyük ölçekli API'nin (Twitter, Stripe, Slack) feed'ler için onu kullanmasının nedeni budur. Güçlü cevaplar operasyonel korkulukları da anar — filtre/sıralama alanlarını whitelist'lemek (index'siz sorgulardan ve injection'dan kaçınmak için) ve `limit`'i sınırlamak (veritabanını korumak için) — bu, bu endpoint'leri production'da çalıştırmış birini yalnızca hakkında okumuş birinden ayırır.

Sayfalama: offset vs cursor

Filtreleme ve sıralama

Neden önemli

İlgili sorular