Documentation Index
Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
Use this file to discover all available pages before exploring further.
Genel Bakış
Cache politikası, politika zinciri içinde bağımsız cache okuma, yazma ve silme işlemlerini gerçekleştirir. Bu politika, API Çağrısı politikasının kendi içindeki cache mekanizmasından (response cache) farklı olarak, geliştiriciye açık şekilde ne zaman cache’e erişileceğini, ne yazılacağını ve ne silineceğini kontrol etme yetkisi verir. Böylece sık değişmeyen veriler (currency rates, user profiles, configuration settings gibi) politika akışında dinamik olarak yönetilebilir.Amacı Nedir?
- Backend servis yükünü azaltarak sistem performansını artırmak.
- API yanıt sürelerini kısaltmak: Cache hit’te arka uçta sorgu yapılmaz.
- Expensive (pahalı) computation veya API çağrılarının sonuçlarını saklayarak tekrar yapılmasını önlemek (örneğin, kolay değişmeyen ürün kataloğu, döviz kurları).
- Politika zinciri içinde veri dönüşümleri sırasında geçici verileri cache’lemek.
- Dinamik cache invalidation (geçersizleştirme) ile cache kontrolünü esnek tutmak.
Çalışma Prensibi
Cache politikası üç ana operasyonu destekler:1. LOOKUP (Oku)
Cache’teki bir entry’i arar. Hit ise hedef Variable’a yazılır ve kalan politika akışına normalde devam edilir (veya Optional exit yapılabilir). Miss ise akış devam eder, Variable’a yazılmaz.- Cache Key: Aranacak entry’nin anahtarı (variable interpolation destekli:
user:#{request.userId},currency:${ENV_CURRENCY}) - Target Variable: Hit durumunda cache değerinin yazılacağı Variable
- Hash Key (İsteğe bağlı): Anahtarı MD5/SHA256 ile hash’le (uzun anahtarlar için)
- TTL Kaynağı: Dinamik (runtime Variable’dan) veya sabit
2. POPULATE (Yaz)
Cache’e bir entry yazılır. Değer bir Variable kaynağından alınır.- Source Variable: Cache’e yazılacak değerin kaynağı (bir Variable)
- Cache Key: Entry’nin kaynağında kaydedileceği anahtar
- Hash Key (İsteğe bağlı): Anahtarı hash’le
- TTL Seçenekleri:
- Sabit TTL: Belirli saniye (örn:
300= 5 dakika) - Dinamik TTL: Bir Variable’dan okunur (örn:
#{response.cacheExpiry})
- Sabit TTL: Belirli saniye (örn:
3. INVALIDATE (Sil)
Cache’ten bir entry’i siler. Örneğin, veri güncellemesi sonrasında eski cache’i temizlemek.- Cache Key: Silinecek entry’nin anahtarı
- Hash Key (İsteğe bağlı): Anahtarı hash’le
Özellikler ve Yetenekler
Temel Özellikler
- Üç İşlem Tipi: LOOKUP, POPULATE, INVALIDATE’i ayrı ayrı veya ihtiyaca göre kombinleyen senaryolar destekle.
- Variable Interpolation: Cache key’de
${}(Environment Variable) ve#{}(Context/Runtime Variable) kullanımı.- Örnek:
user:#{request.userId}→ runtime’dauser:123olur - Örnek:
currency:${ENV_REGION}→currency:EURolur
- Örnek:
- Hash Key Seçeneği: Anahtarı MD5 veya SHA256 ile hash’le (uzun anahtarları normalize etmek için).
- Distributed vs Local Cache: Platform yöneticisi tarafından tanımlanan cache seçimi. Distributed (Hazelcast, Redis benzeri) veya Local (JVM in-memory) desteği.
- Dinamik TTL: Yazılan entry’nin TTL’si, response body’deki bir alan veya Variable’dan okunabilir.
İleri Düzey Özellikler
- Cache Bağlantısı Timeout’u (
cacheConnectionTimeoutInSeconds): Cache servisine bağlantı süresi limit’i. Ayar bulunamazsa varsayılan kullanılır. - Hata İşleme (
errorAction):- CONTINUE: Cache erişim hatası → hata yok sayılır, akış devam eder (Variable yazılmaz veya boş kalır)
- FAULT: Cache erişim hatası → politika fail’ler, hata yanıtı üretilir
- Condition Desteği: Koşul kuralları ile bu politika sadece belirli durumlarda çalışabilir.
- Export/Import: Politika yapılandırması ZIP dosyası olarak dışa aktarılabilir.
- Deploy ve Versiyonlama: Değişiklikleri canlı ortama deploy etme, kullanım raporları.
Kullanım Senaryoları
| Senaryo | Durum | Çözüm (Politika Uygulaması) | Beklenen Davranış |
|---|---|---|---|
| Sık Sorgulan Kur Bilgisi | Döviz kurları 5 dakikada bir güncellenir ancak her istek’te sorgulanmaktadır | LOOKUP: cache_key=currency:#{request.currencyPair} → Target: fetched.rate (cache variable’ı). Hit ise yanıt 100ms. Miss ise Backend API çağrısı, POPULATE ile 5 dakika cache’le | İlk istek backend’e gider, sonraki 5 dakika cache’ten yanıt verilir. 5 dakika sonra otomatik expire, yeniden backend’e gider. |
| Kullanıcı Profili Caching | Profil API’si slow, aynı userId için art arda 10 istek | LOOKUP: cache_key=user:#{request.userId} → Target: userProfile. Hit: hemen yanıt. Miss: Backend çağrısı → response body’sini Variable’a yazma → POPULATE: cache_key=user:#{request.userId}, source=userProfile, TTL=600 | İlk userId=5 için backend çağrısı, 10 dakika cache’lenir. userId=6 yeni cache entry. |
| Veri Güncelleme Sonrası Cache Temizliği | Ürün güncelleme API’sine POST yapıldı, eski cache geçersiz hale geldi | Routing sonrasında hata handler’da INVALIDATE: cache_key=product:#{request.productId} | Update başarılı olursa cache silinir, sonraki istek’te yeni veri çekilir. |
| Async İşlem Sonucu Caching | Ticket oluşturma API’si yanıt 2 saniye. Ticket ID’si 1 saat statik kalıyor | POPULATE: source=createdTicket, cache_key=ticket:#{createdTicket.id}, TTL=3600 | Sonraki identical ticket sorgusunda cache’ten yanıt, API yapılmaz. |
| Koşullu Caching | Premium user’lar için hızlı yanıt, normal user’lar cache’siz | Condition: Header=X-User-Tier, Equals=PREMIUM ile LOOKUP/POPULATE. Normal user: Condition fail → politika skip | Premium user cache’den 50ms, normal user backend’den 500ms |
| Multi-Level Cache | Kurumsal ayarlar nadiren değişir, global cache + user-specific override | LOOKUP 1: cache_key=config:#{request.tenantId} (organization config). Hit ise continue. LOOKUP 2: cache_key=config-override:#{request.userId} (user override). Hit ise latter wins | Global config cache + per-user override mekanizması, ikinci LOOKUP’da override varsa onu kullanır. |
Politika Parametrelerini Yapılandırma
Bu adımda, kullanıcı yeni bir Cache politikası oluşturabilir ya da mevcut politika parametrelerini yapılandırarak cache işlemlerini tanımlayabilir.Yeni Cache Politikası Oluşturma
Yapılandırma Adımları
| Adım | Açıklama / İşlem |
|---|---|
| Adım 1: Oluşturma Sayfasına Gitme | - Sol menüden Development → Global Settings → Global Policies → Cache bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın. |
| Adım 2: Temel Bilgileri Girme | Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: User_Profile_Cache- Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: “Kullanıcı profil bilgilerini 10 dakika cache’ler” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Operation Seçimi ve Temel Ayarları | Operation (İşlem) Zorunlu: Dropdown’dan seçin: - LOOKUP: Cache’ten oku - POPULATE: Cache’e yaz - INVALIDATE: Cache’ten sil Cache Set Name (Cache Seti) Zorunlu: Platform yöneticisinin tanımladığı cache seçimi. Örnek: Distributed Cache veya Local Cache- Dropdown’dan seçin. Tanımlı cache yoksa sistem uyarı gösterir. Cache Key Zorunlu: Anahtar expression. Variable interpolation destekli. Örnek: user:#{request.userId}Örnek: currency:${ENV_REGION}:${current.date}- Runtime’da her iki söz dizimi de çözülür. |
| Adım 4: Operation-Spesifik Ayarlar | LOOKUP Seçiliyse: Target Variable (Hedef Değişken) Zorunlu: Cache’ten okunan değer bu Variable’a yazılır. Örnek: fetched.userProfile- Variable listesinden seçin veya adını yazın. Dynamic TTL (İsteğe bağlı): Toggle ile etkinleştirin. Etkin olduğunda, response body’deki bir alanın TTL olarak kullanılabileceğini belirtir. - TTL Source Variable: JSONPath/XPath ile okunan TTL değeri. Örnek: $.cacheExpiry- TTL Format: ISO_8601, UNIX_EPOCH_SECONDS, UNIX_EPOCH_MILLIS, DURATION_STRING (örn: 1h, 300s)- Offset (saniye): TTL’den güvenlik payı çıkarma. Örnek: 30 (30 saniye erken expire)- Fallback TTL: Parse hatası durumunda kullanılacak sabit TTL (saniye) --- POPULATE Seçiliyse: Source Variable (Kaynak Değişken) Zorunlu: Cache’e yazılacak değerin kaynağı. Örnek: fetched.userProfile (backend’den gelen response’u cache’le)- Variable listesinden seçin. TTL Configuration Zorunlu: TTL Type: - Fixed TTL: Sabit saniye. Örnek: 300 (5 dakika)- Dynamic TTL: Bir Variable’dan oku. Örnek: #{response.ttl}- Dynamic TTL with Source: response body’deki alan. Örnek: JSONPath $.expireAt (ISO tarih döner), format: ISO_8601--- INVALIDATE Seçiliyse: Herhangi bir ek alan yok. Cache Key otomatik silinir. |
| Adım 5: Hash Key (İsteğe Bağlı) | Use Hash Key: Toggle ile etkinleştirin. - Aktif: Anahtar MD5/SHA256 ile hash’lenir (uzun anahtarları normalize etmek için) - Pasif: Anahtar olduğu gibi kullanılır Hash Algorithm: - MD5 (daha hızlı, çakışma riski düşük) - SHA256 (daha güvenli, daha ağır) |
| Adım 6: Hata İşleme (Cache Settings) | Cache Connection Timeout (saniye): Cache servisine bağlanma timeout’u. Varsayılan: 5 saniye. - Örnek: 10 (10 saniye)Error Action (Hata İşleme): Cache erişim hatası durumunda davranış: - CONTINUE: Hata yok sayılır, akış devam eder. Target Variable yazılmaz veya boş kalabilir. - FAULT: Hata üretilir, politika fail’ler. Hata yanıtı istemciye döner. Seçim: Backend cache yoksa CONTINUE, kritik data ise FAULT. |
| Adım 7: Condition (İsteğe Bağlı) | - Condition sekmesine geçin. - Politikanın sadece koşul sağlandığında çalışması isteniyor ise tanımlayın. Örnek: - Header = X-Cache-Enabled, Operator = Equals, Value = true → cache sadece bu header varsa çalışır- Path = /api/products/* → ürün endpoint’leri için cache active |
| Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı) | - Error Message Customization sekmesine gidin. - Cache politikası başarısız olduğunda (Error Action=FAULT) dönecek özel mesajı ayarlayın. Varsayılan: { "statusCode": 500, "message": "Cache operation failed" }Özel: { "statusCode": 503, "errorCode": "CACHE_UNAVAILABLE", "message": "Cache hizmet şu anda erişilemez" } |
| Adım 9: Kaydetme | - Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: - Benzersiz isim - Operation seçili - Cache Set Name seçili - Cache Key dolu - LOOKUP’ta Target Variable dolu - POPULATE’te Source Variable ve TTL dolu Sonuç: - Politika listeye eklenir. - API’lere bağlanabilir. - Global politikaysa otomatik uygulanır. |
Politikayı Silme
Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Nedir? sayfasındaki Politikayı Silme bölümüne bakabilirsiniz.Politikayı Dışa/İçe Aktarma
Bu politikanın dışa aktarma (Export) adımları ve kullanılabilecek seçenekler için Politika Nedir? sayfasındaki Politikayı Dışa/İçe Aktarma bölümüne bakabilirsiniz.Politikayı API’ye Bağlama
Bu politikanın API’lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API’ye Bağlama bölümüne bakabilirsiniz.İleri Düzey Özellikler
| Özellik | Açıklama ve Adımlar |
|---|---|
| Cache Key Interpolation | Cache key’de environment ve context variable’lar kullanarak dinamik anahtar oluşturun. - Environment: cache_key=user:data:${env.region} (region’a göre farklı cache)- Context: cache_key=quote:#{request.quoteId}:#{current.date} (quote ID + tarih kombinasyonu)- Runtime’da otomatik çözümlenir. |
| Multi-Operation Chain (Zincir) | Aynı API Proxy’de birden fazla Cache politikası ile veri akışı oluşturun. - LOOKUP 1: Global config cache - LOOKUP 2: User-specific override - Backend call (miss ise) - POPULATE: Sonucu cache’le |
| TTL Management | Sabit ve dinamik TTL kombinasyonu: - Sabit: 300 saniye (all entries same TTL)- Dinamik: Response’daki $.expiresAt alanından TTL hesapla- Offset: Saat farkı / ağ gecikmesi telafi et (örn: offset=30) |
| Conditional Caching | Sadece belirli durumlarda cache aktif: - Condition: Header=X-Cache-Control, Equals=enable- Error Action: CONTINUE → cache erişim hatası yok say, flow devam et- Cost optimization: Production’da all, staging’de none |
İpuçları ve En İyi Uygulamalar
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Cache Key Tasarımı | Kötü: Generic key: data, cache (çakışma riski)İyi: Spesifik key: user:123:profileEn İyi: Namespace + ID + qualifier: user:#{request.userId}:profile:v2 (versioning) |
| TTL Ayarı | Kötü: Çok uzun TTL (24 saat) - Stale data İyi: Veri güncellenme sıklığına göre (saat → 3600s, dakika → 300s) En İyi: Dinamik TTL + offset. Response’daki TTL okuyarak, offset=30s ile erken expire. |
| Hata İşleme | Kötü: Cache fail → API fail (ERROR_ACTION=FAULT her durumda) İyi: Non-critical data: CONTINUE, kritik data: FAULT En İyi: Cache unavailable ama API çalışıyor: CONTINUE, user feedback yapılmaz. |
| Cache vs Load | Kötü: Tüm endpoint’ler cache (unnecessary memory) İyi: Sık sorgulan, sık değişmeyen veriler (products, config) En İyi: Analytics + usage patterns → cache Only high-volume + low-change data |
| Cache Distribution | Kötü: Local cache (single node, cluster’da sync sorun) İyi: Distributed cache (Hazelcast, Redis) En İyi: Admin’in seçtiği cache strategy’yi politika level’de override etme, global config’e uy. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Hassas Veri Caching | Uyarı: Password, API key, token gibi hassas veri cache’lenmemelidir. Öneri: Sensitive data için NEVER cache. Variable’ı öncelikle verify et: source=userProfile → body’de password yok mu?Kritik: Eğer source’da hassas field varsa INVALIDATE politikasıyla cache sonrası temizle. |
| Cache Key Injection | Uyarı: İstemci-supplied input’u doğrudan cache key’ye yazma. Öneri: Cache key’yi normalize et. Örn: user:#{sanitize(request.param)}Kritik: Cache key collision riskini düşür → hash key enable et. |
| TTL Risk | Uyarı: Çok uzun TTL, stale authorized data serve edilmesi riski. Öneri: Authentication-related data: kısa TTL (60-300 saniye) Kritik: Logout sonrasında credential cache’i INVALIDATE et. |
| Cache Exhaustion / DoS | Uyarı: Attacker çok sayıda unique key produce ederse cache dolar (memory exhaustion). Öneri: Cache capacity limit set et (platform admin). Politika level’de CONTINUE error action kullan. Kritik: Rate limiting + cache key validation ile DoS koruması. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Cache politikası ile API Call politikasının cache’i arasındaki fark nedir? | API Call cache: Response cache, politika içinde otomatik. Cache politikası: Bağımsız LOOKUP/POPULATE/INVALIDATE, geliştiriciye kontrol verir. İki mekanizma birbirinden bağımsız çalışabilir. |
| Genel | Aynı API’de birden fazla Cache politikası kullanabilir miyim? | Evet. Örn: LOOKUP user profile → miss ise backend → POPULATE. Sonra LOOKUP user permissions → miss ise backend → POPULATE. Aynı veya farklı cache set’ler kullanılabilir. |
| Teknik | Hash Key neleri çözer? | Çok uzun cache key’leri (URL’ler, JSON expression’lar) normalize eder. MD5/SHA256 hash ile anahtar sabit boyuta getirilir, cache storage’ı optimize eder. Cache hit/miss oranında fark yoktur, sadece memory efficiency. |
| Teknik | Dynamic TTL’de parse hatası olursa ne olur? | Variable’dan okuma başarısız veya format yanlış ise Fallback TTL kullanılır. Fallback tanımlanmazsa, politika tasarımında tanımlanan sabit TTL (varsa) kullanılır. Hiçbiri yoksa cache’e yazılır ama default system TTL ile. |
| Kullanım | LOOKUP’ta hit varsa akışın sonrasında ne olur? | Hit varsa Target Variable’a yazılır, akış normal devam eder (politika skip değil). Eğer immediate exit isteniyor ise Condition + Set Variable ile kuruş kontrol yapılabilir. |
| Kullanım | INVALIDATE işlemi sırasında key bulunamazsa hata mı? | Hayır. Cache’te key yoksa INVALIDATE silinmiş sayılır, hata dönmez. Error Action bu durumda geçerli değildir (success tarafında). |
| Hata | Cache bağlantı timeout hatası alıyorum. Nedir? | Cache servisine TCP bağlantı bağlanalamıyor. Kontrol: Cache sunucusu ayakta mı? Network firewall? Timeout değeri çok düşük mü (artırın)? Error Action=CONTINUE ile hata yok sayılabilir. |
| Hata | Cache’e yazma başarılı ama okuma miss dönüyor. Nedir? | Cache key farklı olabilir. POPULATE’deki key vs LOOKUP’taki key eşit mi? Variable interpolation’ın runtime’da aynı değer dönüp dönmediğini kontrol et. Örn: user:#{request.userId} — userId değişiyor mu? |
| Performans | Cache politikası overhead’i ne kadardır? | Minimal. Typical: 2-5ms (LOOKUP/POPULATE/INVALIDATE). Distributed cache: +3-10ms network latency. Distributed cache hit: 5-20ms. Backend call: 100-5000ms (hit savings önemli). |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Cache Hit Ratio | Öneri: Cache key tasarımını optimize et. Aynı logical entity için aynı key kullan. hit ratio %80+ hedefi. Etki: Hit %80 → backend call %80 azalır. Response time 10-100x hızlanır. |
| TTL Tuning | Öneri: Data update frequency’ye göre TTL ayarla. Örn: Currency rates 5 min, User profile 10 min, Config 1 hour. Etki: Çok kısa TTL: miss artış. Çok uzun TTL: stale data. Optimal TTL: hit + freshness balance. |
| Distributed vs Local | Öneri: Single node: local cache. Multi-node cluster: distributed cache (consistency). Etki: Local: hızlı (in-process), Distributed: yavaş (RPC) ama cluster-wide consistency. |
| Error Action Tuning | Öneri: Critical path: ERROR_ACTION=FAULT. Non-critical: CONTINUE. Etki: FAULT: safe fail, user feedback. CONTINUE: graceful degrade, backend fallback. |