Içerik filtreleme ve arama

Modern API'ler yalnizca CRUD operasyonlari sunmakla kalmaz; tuketicilerin büyük veri kümeleri uzerinde filtreleme, siralama, arama ve facet ile kesif yapmasini bekler. Kotu tasarlanmis sorgu parametreleri SQL injection riski, performans cokusu ve belirsiz sözleşme yaratir. Iyi tasarlanmis filtreleme ve arama katmanı, REST prensiplerini koruyarak güçlü sorgu ifadesi sunar ve sunucu tarafinda maliyeti kontrol altinda tutar.

Filtreleme parametreleri

En yaygın yaklaşım query string uzerinden alan-deger eslestirmesidir. GET /products?category=electronics&price_min=100&price_max=500 okunabilir ve cache'lenebilir. Alan adlari API dokumantasyonunda whitelist olarak tanimlanmalidir; kullanıcının gonderdigi key dogrudan SQL veya NoSQL sorgusuna enjekte edilmemelidir.

Operator destegi

Basit esitlik yeterli olmadiginda operator suffix veya bracket syntax kullanılır:

GET /orders?created_at[gte]=2026-01-01&created_at[lt]=2026-02-01
GET /users?status[in]=active,pending
GET /items?name[contains]=laptop

Desteklenen operatorler (eq, ne, gt, gte, lt, lte, in, contains) dokumante edilmeli ve sunucu tarafinda whitelist ile dogrulanmalidir.

JSON:API ve OData tarzlari

JSON:API filter[field]=value convention kullanır. OData $filter, $orderby, $top, $skip parametreleri ile standart sorgu dili sunar. OData güçlü ancak implementasyonu agirdir; basit REST API'ler icin minimal filter syntax yeterli olabilir.

• JSON:API: Tutarlı convention, ekosistem destegi.
• OData: Zengin ifade dili, kurumsal araclama.
• Özel DSL: Domain'e özel, dokumantasyon sart.

Siralama ve pagination birlikte

Filtreleme sort ve pagination ile birlikte çalışır. GET /articles?tag=api&sort=-published_at&limit=20&cursor=eyJpZCI6MTIzfQ cursor tabanli sayfalama ile tutarlı sonuç verir. Offset pagination filtre degistiginde duplicate veya skip sorunlarina açıktır.

Tam metin arama

q veya search parametresi genel metin aramasi icin ayrilir. Elasticsearch, OpenSearch, PostgreSQL full-text search veya Azure Cognitive Search arka planda kullanılabilir. API yuzeyi arama motoru detayini gizler.

GET /documents?q=rate+limiting&fields=title,body&highlight=true

Relevance ve scoring

Arama sonuclari relevance skoruna gore siralanir. API score alanini opsiyonel dondurur. Fuzzy matching ve typo tolerance kullanıcı deneyimini iyilestirir ancak index maliyetini artirir.

Facet ve aggregation

E-ticaret ve içerik API'lerinde facet, filtre seceneklerini dinamik gösterir. GET /products?category=shoes&facets=brand,size,color yanitinda hem ürün listesi hem facet bucket'lari doner.

{
  "data": [...],
  "facets": {
    "brand": [{ "value": "Nike", "count": 42 }],
    "size": [{ "value": "42", "count": 18 }]
  }
}

Facet sayimi filtrelenmis kume uzerinden hesaplanir; kullanıcı daralttikca bucket güncellenir.

Güvenlik: injection ve DoS

Kullanıcı girdisi asla ham sorguya birlestirilmemelidir. Parameterized query, ORM ve query builder kullanılır. Regex arama ReDoS riski tasir; timeout ve pattern sınırları uygulanir. Maksimum filter derinligi, alan sayisi ve limit tavanı zorunlu tutulur.

1. Alan whitelist.
2. Operator whitelist.
3. String uzunluk limiti.
4. Sorgu timeout.
5. Rate limit agir arama endpoint'lerinde.

Performans ve indexleme

Filtrelenen ve siralanan alanlar veritabanında indexlenmelidir. Composite index sorgu pattern'ine gore tasarlanir. Full-text arama icin ayri search index senkron tutulur; CDC veya event-driven güncelleme kullanılır.

N+1 ve eager loading

Liste endpoint'lerinde ilişkili veri include veya expand parametresi ile istege bağlı yuklenir. Varsayilan olarak hafif DTO donmek performansi korur.

GraphQL ve field selection

REST'te over-fetching sorunu fields sparse fieldset parametresi ile kismen cozulur: GET /users?fields=id,name,email. GraphQL'de istemci ihtiyaç duydugu alanlari secer; arama ve filtreleme resolver seviyesinde uygulanir.

Cursor ve arama tutarlılığı

Arama sirasinda yeni kayıt eklendiginde offset pagination kayma yapar. Search-after ve cursor mekanizmasi tutarlı sayfalama sağlar. Elasticsearch search_after bu amaca hizmet eder.

API sozlesmesi dokumantasyonu

OpenAPI'de her filter parametresi tip, enum ve açıklama ile tanimlanir. Örnek istekler karmaşık filter kombinasyonlarini gösterir. Desteklenmeyen alan icin 400 ve ProblemDetails donulur.

Test stratejisi

Filter kombinasyonlari icin tablo bazli test yazilir. Edge case: bos filter, celisen aralik, gecersiz operator. Performans testi büyük veri setinde p95 latency olculur.

Özet

Içerik filtreleme ve arama API'sinin en görünür yuzeyidir. Whitelist tabanli güvenli sorgu builder, net operator sozlugu, facet destegi ve arama icin ayri index katmanı başarılı tasarimin temelidir. Pagination ve sort ile birlikte dusunulmeli; dokumantasyon ve örnekler entegrasyon hatalarini azaltir.

Agir arama islemleri ayri endpoint veya async job olarak da sunulabilir. Uzun suren sorgular 202 Accepted ile job id dondurur; istemci polling veya webhook ile sonucu alir. Bu pattern büyük veri export ve raporlama API'lerinde yaygindir.

Geo-spatial filtreleme

Konum bazli API'ler lat, lng ve radius parametreleri kullanır. PostGIS veya Elasticsearch geo_query arka planda çalışır. Mesafe birimi metre veya mil olarak dokumante edilmelidir.

Cok dilli arama

lang parametresi analyzer secimini belirler. Türkçe icin ASCII folding ve stemming dikkatle yapilandirilir. Ayni içeriğin çoklu dil varyantlari locale filtresi ile ayrilir.

Cache ve ETag

Deterministik filter kombinasyonlari cache key oluşturur. GET istekleri CDN cache'lenebilir; kisisellestirilmis filter auth gerektirir ve cache disi birakilir. Vary header ile auth ve Accept-Language ayri cache girişi oluşturur.

Analytics ve arama loglari

Populer arama terimleri ürün ve içerik stratejisine geri bildirim sağlar. Sifir sonuç donen sorgular index veya synonym iyilestirmesi icin sinyal üretir. PII iceren arama loglari maskelenmelidir.

Query plan ve maliyet limiti

Karmaşık filter kombinasyonlari pahali sorgu üretir. API sunucusu tahmini maliyet skoru hesaplayabilir; esik asilirsa 400 veya basitlestirme onerisi doner. Elasticsearch terminate_after ve SQL LIMIT zorunlu tutulur.

Synonym ve alias

Arama kalitesi icin synonym map tanimlanir: laptop, notebook, dizustu. Alias index gecisinde sifir downtime sağlar. API versiyonu degisse de arama davranisi tutarlı kalir.

API tasarımında bu konu operasyonel olgunluk, ölçülebilir metrikler ve tuketici odaklı sözleşme yönetimi ile desteklenmelidir. Ekip icinde karar kayitlari, review surecleri ve otomatik testler kaliteyi sürdürülebilir kilar. Üretim verisi ve geri bildirim dongusu ile politika ve limit degerleri periyodik güncellenir.