API Çağrısı

ipucu

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

Genel Bakış

API Call politikası, API Gateway üzerinden başka REST API'leri çağırarak mikroservis mimarisinde servis-servis iletişimi kurar. Gelen istekleri backend sistemlere yönlendirir, yanıtları işler ve API Proxy akışına entegre eder. Bu sayede harici servislerden veri çekmek, istekleri zenginleştirmek veya birden fazla kaynaktan gelen yanıtları birleştirmek mümkün olur.

Amacı Nedir?

• API Gateway üzerinden geçen istekleri başka bir REST API'ye yönlendirerek mikroservis mimarilerinde servis-servis iletişimini sağlamak.
• Gelen istekleri zenginleştirmek, dönüştürmek ve birden fazla backend servisinden veri toplayarak birleştirilmiş yanıtlar oluşturmak (API Orchestration).
• Harici sistemlerden (CRM, ERP, ödeme gateway'leri vb.) veri çekmek veya veri göndermek için güvenli ve yönetilebilir bir köprü oluşturmak.
• Request ve Response mesajları üzerinde header, parameter ve body manipülasyonu yaparak veri dönüşümü gerçekleştirmek.
• Cache mekanizması ile sık kullanılan API çağrılarının sonuçlarını önbelleğe alarak performansı artırmak ve backend sistemlere olan yükü azaltmak.

Çalışma Prensibi

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, REST API Call politikası aktif ise çağrı işlemi başlatılır.
2. Politika Kontrolü: Sistem aşağıdaki sırayla kontrol yapar:
   • Condition (koşul) tanımlı mı? Varsa koşul sağlanıyor mu?
   • Politika aktif mi (active=true)?
   • Variable kullanılıyor mu yoksa Apinizer default mı?
3. Request Hazırlama (Before Call): İstek gönderilmeden önce:
   • Body temizlenir veya yeni içerik eklenir
   • Header ve parametreler manipüle edilir (ekleme/silme)
   • Data Manipulation kuralları uygulanır
   • Cache kontrolü yapılır (varsa önbellekten döner)
4. API Çağrısı: Tanımlanan URL'ye HTTP method ile istek gönderilir:
   • Synchronous (Senkron): Yanıt beklenir ve işleme devam edilir
   • Asynchronous (Asenkron): Yanıt beklenmeden işlem tamamlanır
5. Response İşleme (After Call - Sadece Synchronous): Gelen yanıt işlenir:
   • Body üzerinde dönüşüm yapılır (NOT_CHANGE, REPLACE, CLEAR)
   • Header ve parametreler manipüle edilir
   • Data Manipulation kuralları uygulanır
   • Cache'e kaydedilir (aktifse)
6. Hata İşleme: Bağlantı hatası, timeout veya beklenmeyen yanıtlar için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.

Özellikler ve Yetenekler

Temel Özellikler

• Çağrı Tipi Seçimi: Synchronous (yanıt bekle) veya Asynchronous (fire-and-forget) mod desteği. Asenkron modda yanıt işleme yapılmaz.
• HTTP Method Desteği: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE tüm HTTP methodlarını destekler.
• Timeout Yönetimi: API çağrılarında maksimum bekleme süresini saniye cinsinden tanımlayarak sonsuz beklemeleri önler ve sistem kaynaklarını korur.
• Aktif/Pasif Durum Kontrolü: Politikanın aktif veya pasif durumunu kolayca değiştirme (active/passive toggle). Pasif durumda politika uygulanmaz ancak yapılandırması saklanır.
• Koşul Bazlı Uygulama: Query Builder ile karmaşık koşullar oluşturarak politikanın ne zaman uygulanacağını belirleme (örn: sadece belirli endpoint'lere veya header değerlerine göre).

İleri Düzey Özellikler

• Request/Response Manipülasyonu: Before Call ve After Call aşamalarında body, header ve parametreler üzerinde kapsamlı manipülasyon. XML, JSON, RAW, URL-Encoded formatlarını destekler.
• Data Manipulation: Kaynak ve hedef değişkenler arasında ADD (ekle), REPLACE (değiştir), DELETE (sil) operasyonları ile veri dönüştürme. Variable sistemini kullanarak dinamik veri işleme.
• Güvenli HTTPS ve mTLS: İstek Settings sekmesinde zaman aşımı ve güvenli bağlantı (TrustStore, KeyStore, isteğe bağlı PEM sertifikası, protokoller, hostname doğrulayıcı) ile arka uçta TLS/mTLS kullanabilirsiniz; sertifika ve KeyStore yönetimi Secret Manager ile uyumludur.
• Cache Mekanizması: Distributed (dağıtık) veya Local (yerel) cache desteği. Variable bazlı cache key tanımlama, capacity ve TTL ayarları, null response'ları cache'leme seçeneği.
• Test Helper: API çağrısı için URL'yi otomatik oluşturma. Mevcut API Proxy'lerden veya Proxy Group'lardan endpoint seçimi, environment bazlı test yapma.
• Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) import etme. Versiyon kontrolü ve yedekleme imkanı.
• Policy Group ve Proxy Group Desteği: Birden fazla politikayı Policy Group içinde yönetme. Proxy Group'lara toplu politika atama. Merkezi güncelleme ve deploy işlemleri.
• Deploy ve Versiyonlama: Politika değişikliklerini canlı ortama deploy etme. Hangi API Proxy'lerde kullanıldığını görme (Policy Usage). Proxy Group ve Policy Group kullanım raporları.

Kullanım Senaryoları

Senaryo	Durum	Çözüm (Politika Uygulaması)	Beklenen Davranış / Sonuç
Mikroservis Entegrasyonu	Sipariş API'si, ödeme servisini çağırmalı	REST API Call politikası ile sipariş endpoint'ine gelen isteklerde ödeme servisine POST çağrısı yapılır. Body'de sipariş bilgileri gönderilir.	Ödeme servisi yanıtı alınır, başarılı ise sipariş onaylanır. Timeout 30 saniye.
Veri Zenginleştirme	Kullanıcı profil API'si, sadece ID ile gelir ancak detaylı bilgi gerekir	Gelen istek body'sindeki userId ile CRM sistemine GET çağrısı yapılır. Data Manipulation ile CRM yanıtı mevcut response'a eklenir.	İstemciye kullanıcı ID'si + tam profil bilgisi (ad, soyad, email) birleştirilmiş şekilde döner.
Authentication Token Yönetimi	Backend servisi API Key yerine JWT token bekliyor	Request Header'larından X-API-Key alınır, Authentication API'sine gönderilir. Dönen JWT token, Before Call aşamasında Authorization header'ına eklenir.	Backend servisi geçerli JWT token ile çağrılır. İstemci API Key kullanmaya devam eder.
Cache ile Performans	Ürün katalog API'si her çağrıda veritabanına gidiyor	REST API Call ile catalog servisi çağrılır. Cache aktif, capacity: 1000, TTL: 300 saniye. Cache By: "product.category" variable'ı. Storage: Distributed.	İlk çağrıda backend'e gidilir, sonuç 5 dakika cache'lenir. Aynı kategori için yapılan çağrılar cache'ten dönülür.
Async Log Gönderimi	Her API çağrısını harici log sistemine kaydetmek gerekiyor	Asynchronous REST API Call ile log servisine POST yapılır. Body'de request detayları gönderilir. Timeout: 5 saniye.	Log servisi yanıtı beklenmez, ana istek akışı kesintisiz devam eder. Fire-and-forget mantığı.
Üçüncü Parti API Gateway	Ödeme gateway'i özel header formatı bekliyor	Before Call aşamasında tüm header'lar silinir (removeAllHeadersBeforeCall: true). Yeni header'lar eklenir: X-Merchant-ID, X-Transaction-Type, Authorization (Bearer token). Body XML'den JSON'a dönüştürülür.	Ödeme gateway'i beklediği formatta istek alır, entegrasyon başarılı olur.
Certificate ile Güvenli İletişim	Backend servisi mutual TLS (mTLS) gerektiriyor	İstek Settings sekmesinde güvenli bağlantıyı açıp Yapılandır ile KeyStore ve TrustStore seçin. URL: https://secure-backend/api. Timeout: 60 saniye.	İstek istemci sertifikası ile gönderilir, backend karşılıklı TLS ile doğrular, güvenli iletişim sağlanır.

Politika Parametrelerini Yapılandırma

Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir. Tanımlanan parametreler, politikanın çalışma şeklini (örneğin hangi IP'lerin izinli olacağı, coğrafi kısıtlamalar, koşullu aktivasyonlar vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.

Yeni API Call 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 → API Call 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: Payment_Gateway_Call - 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: "Ödeme gateway'ine sipariş onayı için API çağrısı yapar" - Maks. 1000 karakter. - Politikanın amacını açıklayın.
Adım 3: Çağrı Tipini ve Temel Ayarları Yapılandırma	Call Type (Çağrı Tipi): - SYNCHRONOUS: Yanıt beklenir, işleme devam edilir. Response işleme yapılır. - ASYNCHRONOUS: Fire-and-forget. Yanıt beklenmez, response işleme yapılmaz. HTTP Method Zorunlu: Dropdown'dan seçin (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE) Base URL Zorunlu: Örnek: https://api.payment-gateway.com/v2/charge - Test Helper (⚙️ ikonu) ile mevcut API Proxy'lerden URL seçebilirsiniz. Timeout Zorunlu: Saniye cinsinden. Örnek: 30 (30 saniye). Min: 1. - API yanıt vermezse bu süre sonunda timeout hatası dönülür.
Adım 4: Request (Before Call) Yapılandırması	BODY Sekmesi: Clear Body Before Call: Toggle ile aktif/pasif - Aktif: Gelen istek body'si temizlenir. - Pasif: Gelen body aynen kullanılır. Use Message Template (Clear Body aktifse): - Content Type: XML, JSON, RAW, URL_ENCODED - Body Content: Textarea'ya şablon girin. Variable kullanabilirsiniz: ${variable.name} - URL Encoded seçiliyse: Key-Value tablosu görünür. Request Data Manipulation: - [+ Add] butonuna tıklayın. - Operation: ADD, REPLACE, DELETE - Source: Value veya Variable - Target: Value veya Variable (ADD'de targetName zorunlu) HEADER Sekmesi: Remove All Headers Before Call: Toggle - Aktif: Tüm header'lar silinir. - Pasif: Header'lar korunur. Deleted Headers (Remove All pasifse): - Silinecek header adlarını liste halinde ekleyin: X-Old-Header New Headers: - Name, Description, Value/Variable, Prefix (Variable seçiliyse: BEARER, BASIC vb.) - Örnek: Name: Authorization, Value: Bearer ${token.jwt}, Prefix: BEARER PARAMETER Sekmesi: - Header ile aynı mantık. Query parameter'leri için kullanılır. CACHE Sekmesi: Enable Cache: Toggle Apply By (Cache By): Variable seçin (örn: user.id, product.category) Capacity Zorunlu: Örnek: 1000 (1000 kayıt) TTL Zorunlu: Saniye cinsinden. Örnek: 300 (5 dakika) Cache Storage Type: DISTRIBUTED (dağıtık) veya LOCAL (yerel) Cache Null Responses: Checkbox - Null yanıtlar da cache'lensin mi? Dinamik TTL (Dynamic TTL): Toggle ile aktif edin. Aktif edildiğinde cache TTL değeri, API çağrısının yanıtından dinamik olarak hesaplanır. Detaylı açıklama için Dinamik TTL bölümüne bakın. Yanıt Doğrulaması (Response Assertion): Toggle ile aktif edin. Sunucu HTTP 200 dönüp gövdede iş hatası bildirdiğinde, hatalı yanıtın cache'lenmesini engeller. Detaylı açıklama için Yanıt Doğrulaması bölümüne bakın. SETTINGS Sekmesi: Timeout: Saniye cinsinden, zorunlu. İstek süresini bu sekmeden yönetebilirsiniz; üst bölümdeki çağrı timeout değeriyle tutarlı tutmanız önerilir. Güvenli bağlantı (mTLS) ayarları: Başlık altında güvenli bağlantıyı etkinleştir anahtarı ile açın. Açıkken özet alanında KeyStore durumu, tanımlıysa TrustStore ve sunucu sertifikası (PEM), seçilen TLS protokolleri ve hostname doğrulayıcı türü görüntülenir. Ayrıntılı düzenleme için Yapılandır (dişli) düğmesine tıklayın; güvenli bağlantı kapalıyken düğme devre dışıdır. Yapılandır penceresinde: SSL doğrulamayı atla açıksa sunucu sertifikası doğrulanmaz ve TrustStore, KeyStore ile sertifika panelleri kullanılamaz; yalnızca güvenilir test ortamlarında değerlendirin. Kapalıyken TrustStore ve KeyStore için havuzdaki kaydı seçebilir veya + ile yeni KeyStore oluşturabilirsiniz; Sertifika için PEM sertifikayı havuzdan seçebilir veya yeni sertifika tanımlayabilirsiniz. Protokol ayarları bölümünde desteklenen TLS sürümlerini ve hostname doğrulayıcıyı seçebilirsiniz. Bu politika ekranında dosya yükleme yerine havuzdan seçim ve yeni kayıt oluşturma kullanılır; pencerenin altında uyarı metni gösterilir. Kaydet ile değişiklikleri uygulayıp pencereyi kapatırsınız.
Adım 5: Response (After Call) Yapılandırması (Sadece SYNCHRONOUS)	BODY Sekmesi: After Call Body Operation Type: - NOT_CHANGE_BODY: Gelen yanıt aynen döndürülür. - REPLACE_BODY: Gelen yanıt tamamen değiştirilir. - CLEAR_BODY: Gelen yanıt temizlenir, yeni body oluşturulur. Use Message Template (CLEAR_BODY seçiliyse): - Content Type: XML, JSON - Body Content: Textarea'ya yanıt şablonu girin. Original Message Data Manipulation: - Before Call ile aynı mantık. Gelen yanıt üzerinde ADD, REPLACE, DELETE. HEADER ve PARAMETER Sekmeleri: - Request ile aynı yapı. After Call için header/parameter manipülasyonu.
Adım 6: Koşul Tanımlama (İsteğe Bağlı)	- Condition sekmesine geçin. - Koşullar, politikanın hangi durumda aktif olacağını belirler. Örnekler: - Ortam bazlı: Header = X-Environment, Operator = Equals, Value = production - API Key bazlı: Header = X-API-Key, Starts With = PROD- - Endpoint bazlı: Path = /api/payment/*
Adım 7: Hata Mesajı Özelleştirme (İsteğe Bağlı)	- Error Message Customization sekmesine gidin. - API çağrısı başarısız olduğunda dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 500, "message": "REST API call failed" } Özel: { "statusCode": 502, "errorCode": "PAYMENT_GATEWAY_ERROR", "message": "Ödeme servisi yanıt vermiyor", "timestamp": "${current.time}" }
Adım 8: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir IP veya grup mevcut Sonuç: - Politika listeye eklenir. - API'lere bağlanabilir. - Global politikaysa otomatik uygulanır.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

Politikayı Silme

Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.

Politikayı Dışa/İçe Aktarma

Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına 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

Bu bölümde kullanıcı, API Call politikasının gelişmiş yönetim kabiliyetlerini kullanarak daha esnek, dinamik ve kurumsal seviyede kontrol elde eder.

Özellik	Açıklama ve Adımlar
Variable Bazlı Dynamic URL	URL içinde variable kullanarak dinamik endpoint'ler oluşturabilirsiniz. - Variable tanımlayın: backend.base.url = https://api.backend.com - URL alanına: ${backend.base.url}/users/${user.id}/profile - Runtime'da değerler otomatik doldurulur.
Chained API Calls (Zincir Çağrılar)	Birden fazla REST API Call politikasını sıralı çalıştırarak veri akışı oluşturabilirsiniz. - İlk politika ile Authentication API'sini çağırın, token alın. - Token'ı variable'a kaydedin: auth.token - İkinci politikada Authorization header'ına ${auth.token} ekleyin. - İkinci politika ile Data API'sini çağırın.
Conditional Caching	Sadece belirli durumlarda cache aktif olur. - Cache'i aktif edin. - Condition bölümünde: Header = X-Cache-Control, Equals = enable - İstemci cache istediğinde header göndererek cache'i aktif eder.

Dinamik TTL (Dynamic TTL)

Dinamik TTL, cache'in yaşam süresini (TTL) sabit bir değer yerine API yanıtından gelen bir değere göre otomatik hesaplar. Örneğin, backend servisiniz yanıtta bir expireAt alanı dönüyorsa, cache bu tarihe kadar geçerli olur.

Yapılandırma Alanları

Alan	Açıklama
Dinamik TTL Etkinleştir	Toggle ile aktif/pasif. Aktif edildiğinde sabit TTL alanı gizlenir ve dinamik TTL ayarları görünür.
TTL Kaynak Değişkeni	TTL bilgisinin okunacağı değişken. Response header, response body (JSONPath/XPath) veya başka bir context variable olabilir. Örnek: Response body'deki $.expireAt alanı.
Değer Formatı	Seçilen değişkenden okunan değerin formatını belirtir. Aşağıdaki formatlar desteklenir:

Desteklenen Değer Formatları:

Format	Açıklama	Örnek Değer
ISO 8601 DateTime	ISO 8601 standart tarih formatı. UTC, offset veya timezone'suz kabul edilir.	2026-03-26T15:30:00Z, 2026-03-26T15:30:00+03:00, 2026-03-26T15:30:00, 2026-03-26
Özel Tarih Formatı	Java DateTimeFormatter pattern'i ile özel format. Seçildiğinde ek bir pattern alanı görünür.	Pattern: dd.MM.yyyy HH:mm:ss → Değer: 26.03.2026 15:30:00
Unix Epoch (saniye)	Unix epoch timestamp (saniye cinsinden).	1743004200
Unix Epoch (milisaniye)	Unix epoch timestamp (milisaniye cinsinden).	1743004200000
Expires In (saniye)	Yanıtın kaç saniye geçerli olduğunu belirten göreli süre.	300 (5 dakika)
Expires In (milisaniye)	Yanıtın kaç milisaniye geçerli olduğunu belirten göreli süre.	300000 (5 dakika)
Süre String	İnsan okunabilir süre string'i.	1h, 30m, 3600s

Ek Ayarlar

Alan	Açıklama
Değer JWT Token İçinde	Checkbox. Seçildiğinde kaynak değişkendeki değer önce JWT token olarak decode edilir, ardından belirtilen claim'den TTL değeri okunur.
JWT Claim Adı	JWT decode sonrası okunacak claim adı. Basit claim adı (örn: exp) veya JSONPath (örn: $.data.expireAt) desteklenir.
Offset (saniye)	Hesaplanan TTL'den düşülecek güvenlik payı (saniye). Örneğin 30 saniye offset ile cache, expire time'dan 30 saniye önce geçersiz olur. Saat farkı veya ağ gecikmesini telafi etmek için kullanılır.
Yedek TTL (saniye)	Dinamik TTL hesaplanamadığında (parse hatası, değişken bulunamadı vb.) kullanılacak yedek TTL değeri (saniye cinsinden). Tanımlanmazsa politikanın sabit TTL değeri kullanılır.

Örnek Senaryo

Backend servisiniz aşağıdaki gibi bir yanıt dönüyor:

{
  "data": { "price": 99.90, "currency": "TRY" },
  "expireAt": "2026-03-26T15:30:00Z"
}

Bu durumda yapılandırma:

1. Dinamik TTL Etkinleştir: Açık
2. TTL Kaynak Değişkeni: Response body → JSONPath: $.expireAt
3. Değer Formatı: ISO 8601 DateTime
4. Offset: 30 (30 saniye güvenlik payı)
5. Yedek TTL: 300 (parse hatası olursa 5 dakika)

Cache, expireAt alanındaki tarihe kadar (eksi 30 saniye offset) geçerli olacaktır.

Süresi geçmiş tarihler

Hesaplanan TTL sıfır veya negatifse (kaynak değişkendeki tarih geçmişte kalmışsa) yanıt cache'lenmez. Bazı servisler başarısız yanıtlarda 0001-01-01T00:00:00 gibi "boş tarih" değerleri döner; bu değerler de geçmiş tarih sayılır ve cache dışı bırakılır.

Yanıt Doğrulaması (Response Assertion)

Bazı servisler hata durumunda da HTTP 200 döner ve başarısızlığı yalnızca yanıt gövdesindeki bir alanla bildirir:

{ "Token": "", "ReturnCode": 330, "ErrorMessage": "Bad Request" }

Bu tür yanıtlar HTTP durum koduna bakılarak ayırt edilemez; cache açıksa hatalı yanıt da cache'lenir ve TTL boyunca tüm isteklere aynı hata döner. Yanıt doğrulaması, başarıyı gövdedeki (veya header'daki) bir değerden anlamanızı sağlar.

Doğrulama varsayılan olarak kapalıdır. Açmadığınız sürece mevcut yapılandırmalar bugünkü davranışını birebir korur.

Yapılandırma Alanları

Alan	Açıklama
Yanıt Doğrulaması Etkinleştir	Ana anahtar. Kapalıyken her yanıt (HTTP başarılı olduğu sürece) cache'lenir.
Doğrulama Değişkeni	Karşılaştırılacak değerin okunacağı değişken. Response header, response body (JSONPath/XPath) veya başka bir context variable olabilir. Örnek: $.ReturnCode.
Karşılaştırma	Eşittir, Eşit Değildir, İçerir, İçermez, Dolu (Değer Var), Boş (Değer Yok), Regex ile Eşleşir.
Beklenen Değer	Karşılaştırılacak değer. Dolu/Boş operatörlerinde istenmez. Ortam değişkeni (${degisken}) ve context değişkeni (#{degisken}) kullanılabilir; değer her istekte yeniden çözülür. Böylece beklenen değer ortamdan ortama (dev/test/prod) farklı olabilir.

Doğrulama Başarısız Olursa Ne Olur

Yanıt cache'lenmez; akış normal şekilde devam eder ve hatalı yanıt çağıran tarafa iletilir. İstek gateway'de durdurulmaz.

Bu davranış, sık karşılaşılan bir sorunu önler: geçici bir backend hatasının cache'e yazılıp TTL boyunca tüm isteklere dönmesi.

Örnek Senaryo

Yukarıdaki token servisi için:

1. Yanıt Doğrulaması Etkinleştir: Açık
2. Doğrulama Değişkeni: Response body → JSONPath: $.ReturnCode
3. Karşılaştırma: Eşittir
4. Beklenen Değer: 0

ReturnCode 0 dönen başarılı yanıtlar cache'lenir; 330 gibi hata kodu dönen yanıtlar cache dışı bırakılır ve bir sonraki istek backend'e gider.

Dinamik TTL ile birlikte kullanım

İki özellik birbirini tamamlar. Backend'iniz hatalı yanıtlarda geçerli bir sona erme tarihi dönmüyorsa dinamik TTL zaten cache'i engeller; ancak başarı/başarısızlık ayrımı gövdedeki bir koda dayanıyorsa yanıt doğrulamasını da açmanız önerilir.

Hata Alınırsa Yeniden Deneme (Retry)

Hedef servise yapılan çağrı geçici bir hatayla düştüğünde — bağlantı zaman aşımı, DNS veya TLS hatası, ya da karşı tarafın anlık 502/503/504 yanıtı — isteğin tamamını hataya düşürmek yerine çağrı otomatik olarak yeniden gönderilebilir.

Retry varsayılan olarak kapalıdır. Siz açana kadar mevcut yapılandırmalar bugünkü davranışını birebir korur.

Yapılandırma Alanları

Alan	Açıklama
Hata alınırsa yeniden dene	Ana anahtar. Kapalıyken çağrı eskisi gibi tek kez denenir.
Yeniden Deneme Sayısı	İlk denemeden sonra yapılacak ek deneme sayısı. Toplam istek sayısı bu değerin bir fazlasıdır.
Bekleme Stratejisi	Gecikme Yok, Sabit Gecikme veya Üstel Bekleme.
Sabit Bekleme (ms)	Her yeniden denemeden önce beklenecek süre. Sabit Gecikme seçiliyken görünür.
İlk Bekleme (ms)	İlk yeniden denemeden önceki bekleme. Üstel Bekleme seçiliyken görünür.
En Fazla Bekleme (ms)	Artan bekleme süresinin üst sınırı; böylece gecikme sınırsız büyümez.
Artış Çarpanı	Her adımda uygulanan büyüme katsayısı (1'den büyük olmalıdır).
Yeniden Denenecek Durum Kodları	Hangi HTTP durum kodlarının yeniden denemeyi tetikleyeceği. Boş bırakılırsa 502, 503 ve 504 kullanılır.
POST/PATCH çağrılarında sunucu hatasında da yeniden dene	Varsayılan kapalı. Aşağıdaki uyarıya bakınız.

Hangi Hatalarda Yeniden Denenir

Karar yalnızca durum koduna değil, isteğin ne kadar ilerlediğine göre verilir:

Durum	Anlamı	Yeniden denenir mi?
Bağlantı hiç kurulamadı (bağlantı reddedildi, connect timeout, DNS hatası, TLS el sıkışma hatası)	İstek gönderilmedi	Evet, her HTTP metodunda
İstek gönderildi ama yanıt alınamadı (read timeout, bağlantının kapanması)	Servis isteği işlemiş olabilir	Yalnızca idempotent metotlarda
Servis, listedeki bir hata koduyla yanıt verdi	Servis isteği işlemiş olabilir	Yalnızca idempotent metotlarda
Diğer durumlar (örneğin 400, 401, 404)	Kalıcı hata, tekrar denemek çözmez	Hayır

RFC 7231'e göre GET, HEAD, OPTIONS, PUT ve DELETE idempotenttir; POST ve PATCH değildir.

uyarı

POST/PATCH çağrılarında sunucu hatasında da yeniden dene seçeneğini yalnızca hedef servis tekrarlanan isteklere karşı güvenliyse açın. Servis, isteği işledikten sonra hata döndürmüşse yeniden göndermek çift kayıt veya çift ödeme oluşturabilir. Bağlantı hiç kurulamadığında ise istek karşı tarafa ulaşmamıştır; bu durumda ayardan bağımsız olarak yeniden denenir.

Cache ile Etkileşimi

Retry ve yanıt cache'i birbirinden ayrı eksenlerde çalışır, birbirini bozmaz:

• Yanıt cache'ten karşılandığında hiç HTTP çağrısı yapılmaz; dolayısıyla retry hiç devreye girmez.
• Cache, denemeler başlamadan bir kez sorgulanır; yeniden denemeler cache sorgusunu tekrarlamaz.
• Cache'e yalnızca başarılı yanıt yazılır. Tüm denemeler başarısız olursa hiçbir şey cache'lenmez ve politika bugünkü gibi hata verir.
• Dinamik TTL kullanılıyorsa TTL, son ve başarılı yanıttan hesaplanır; başarısız denemeler TTL'yi etkilemez.
• Cache servisine erişilememesi ayrı bir konudur ve retry ile değil, cache hata davranışı ayarıyla yönetilir.

uyarı

Her deneme, tanımlı zaman aşımı kadar sürebilir ve beklemeler bunun üzerine eklenir. 30 saniye zaman aşımı ve 2 yeniden deneme ile çağrı yaklaşık 90 saniye sürebilir. Bu sürenin API proxy'nin genel zaman aşımını aşmamasına dikkat edin — politika ekranı, değerleri değiştirdikçe hesaplanan en kötü durumu gösterir.

Trace Üzerinde Görünürlüğü

Trace açıkken her deneme ayrı ayrı kaydedilir. Yürütme detayında toplam deneme sayısı ve her deneme için sonucu, hata sınıfı, süresi ve öncesinde beklenen süre görünür; böylece uzun süren bir istek sonradan açıklanabilir.

Sıkıştırma (Compression)

Politika varsayılan olarak hedef servisle sıkıştırma pazarlığı yapmaz: Accept-Encoding başlığı gönderilmez ve yanıt geldiği biçimde iletilir. Pazarlığı Ayarlar sekmesindeki Sıkıştırmayı Etkinleştir seçeneğiyle açabilirsiniz.

Etkinleştirildiğinde çağrı, hedef servise kabul ettiği sıkıştırma biçimlerini (gzip, deflate, br, zstd ve platformda bulunan diğer biçimler) bildirir ve sıkıştırılmış bir yanıt geldiğinde politikanın geri kalanı çalışmadan önce yanıtı otomatik olarak açar. Büyük yanıtlarda bu, aktarılan veri miktarını azaltır.

Ne Zaman Etkinleştirmelisiniz

Durum	Öneri
Hedef servis yavaş veya ücretli bir hat üzerinden büyük yanıtlar dönüyor	Etkinleştirin — yanıt sıkıştırılmış olarak taşınır ve otomatik açılır.
Hedef servis, çağıranın kabul ettiği biçime bakmaksızın sıkıştırılmış yanıt dönüyor	Etkinleştirin — aksi hâlde yanıt sıkıştırılmış biçimde taşınır ve sonraki adımlar okuyamaz.
Hedef servis düz yanıt dönüyor	Kapalı bırakın — varsayılan budur ve gereksiz pazarlığı önler.

not

Accept-Encoding başlığı yalnızca bu ayarla yönetilir. Header sekmesinde bu başlık için tanımladığınız bir değer hedef servise iletilmez.

uyarı

Sıkıştırma varsayılan olarak kapalıdır; bu nedenle bu ayar eklenmeden önce yapılandırılmış API Çağrısı politikaları yükseltmeden sonra Accept-Encoding göndermeyi bırakır. Hedef servis, çağıranın kabul ettiği biçime bakmadan sıkıştırılmış yanıt dönüyorsa, o servisi çağıran politikalarda bu ayarı etkinleştirin.

İpuçları ve En İyi Uygulamalar

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
URL Yönetimi	Kötü: URL'leri hard-code olarak yazma: https://api.prod.com/users İyi: Environment variable kullanma: ${env.api.url}/users En İyi: Variable + Config ile ortam bazlı yönetim: Test ortamında ${backend.url} = https://test-api.com, Production'da https://prod-api.com
Timeout Değerleri	Kötü: Çok yüksek timeout (120 saniye) - Sistem kaynakları tükenir İyi: Ortalama timeout (30 saniye) - Çoğu durumda yeterli En İyi: Backend servisi response time'ına göre optimize edilmiş timeout. Database sorguları: 10 saniye, Harici API: 30 saniye, Ödeme: 60 saniye
Cache Stratejisi	Kötü: Tüm API'lere aynı cache ayarı - Gereksiz cache İyi: Endpoint bazlı cache - Ürün listesi: 5 dakika En İyi: Variable bazlı cache + Null response kontrolü. Cache By: user.tier → Premium user: 1 dakika, Free user: 10 dakika. Cache Null Responses: false (boş yanıtlar cache'lenmesin)
Error Handling	Kötü: Varsayılan hata mesajları - Kullanıcı anlamaz İyi: Özel hata mesajları - "Backend servisi yanıt vermiyor" En İyi: HTTP status code + custom error code + contextual message: { statusCode: 504, errorCode: "PAYMENT_TIMEOUT", message: "Ödeme servisi 30 saniye içinde yanıt vermedi", retryAfter: 60 }
Header Manipulation	Kötü: Tüm header'ları silip manuel ekleme - Güvenlik riski İyi: Sadece gerekli header'ları ekleme/silme En İyi: Remove All Headers: false. Sadece hassas header'ları sil (Authorization, Cookie). Backend'in ihtiyacı olan header'ları ekle. Trace için correlation-id ekle.

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Certificate Kullanımı	Uyarı: HTTPS backend'lere certificate olmadan bağlanmak güvenlik açığı oluşturur. Öneri: Mutual TLS (mTLS) gerektiren sistemlere mutlaka certificate ekleyin. Certificate revoke kontrolü yapın. Expired sertifikalar uyarı verir. Kritik: Production ortamında self-signed certificate kullanmayın.
Hassas Veri İletimi	Uyarı: API Key, token, password gibi bilgileri body içinde plain text göndermeyin. Öneri: Hassas verileri Variable olarak tanımlayın, encrypted saklayın. Header'da gönderin: Authorization: Bearer ${secure.token} Kritik: Log'lara hassas veri düşmemesine dikkat edin. Data Manipulation'da password alanlarını mask edin.
Asynchronous Call Güvenliği	Uyarı: Asenkron çağrılarda yanıt kontrol edilemez, hata gözden kaçabilir. Öneri: Kritik operasyonlar için Synchronous kullanın. Asenkron sadece log, notification gibi yan işlemler için kullanın. Kritik: Ödeme, sipariş onayı gibi işlemler asıl yanıt alınmadan tamamlanmamalı.
Input Validation	Uyarı: Gelen istekleri doğrulamadan backend'e göndermeyin. Öneri: Before Call aşamasında input validation ekleyin. XSS, SQL Injection riskli karakterleri filtreleyin. Data Manipulation ile sanitization yapın. Kritik: Backend'in beklediği format dışında veri gönderilmemesini sağlayın.
Rate Limiting	Uyarı: REST API Call politikası rate limiting yapmaz, backend overload olabilir. Öneri: REST API Call ile birlikte Rate Limiting politikası kullanın. Backend sistemine aşırı yük atmayın. Kritik: DDoS koruması için API Gateway seviyesinde rate limiting şart.

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Sonsuz Timeout	Neden kaçınılmalı: Timeout değeri çok yüksek olursa (örn: 300 saniye), yanıt vermeyen backend'ler sistem kaynaklarını tüketir. Connection pool dolabilir. Alternatif: Makul timeout değerleri kullanın (5-60 saniye arası). Backend servisi optimize edin. Gerekirse async call kullanın.
Cache Olmadan Yoğun Çağrı	Neden kaçınılmalı: Aynı veriyi defalarca çağırmak backend'i yorar, response time artar, maliyet artar. Alternatif: Sık değişmeyen veriler (ürün katalog, ayarlar) için cache aktif edin. TTL'yi veri güncelleme sıklığına göre ayarlayın.
Gereksiz Data Manipulation	Neden kaçınılmalı: Her request/response'da karmaşık data manipulation yapmak performansı düşürür. CPU kullanımı artar. Alternatif: Backend servisini değiştirerek veriyi istenen formatta göndermeyi tercih edin. Sadece gerektiğinde data manipulation kullanın.
Global Politikada Sık Değişiklik	Neden kaçınılmalı: Global politika birden fazla API'de kullanılıyorsa, bir değişiklik tüm API'leri etkiler. Production'da hata riski artar. Alternatif: Test ortamında global politikayı test edin. Kritik API'ler için local politika kullanın. Değişiklik öncesi backup alın.

Performans İpuçları

Kriter	Öneri / Etki
Connection Reuse	Öneri: Apinizer backend bağlantıları connection pool ile yönetir. Aynı backend'e birden fazla çağrı yapılıyorsa connection reuse edilir. Etki: Her çağrıda yeni TCP bağlantısı açılmaz, latency azalır. SSL handshake overhead'i düşer.
Cache Hit Ratio	Öneri: Cache capacity'yi çok düşük tutmayın. Yoğun kullanılan endpoint'lere yüksek capacity verin. Cache By ile doğru key seçimi yapın. Etki: Cache hit ratio %80+ olursa backend load %80 azalır. Response time 10-100x hızlanır.
Async vs Sync Seçimi	Öneri: Kritik olmayan, yavaş, yanıt gerektirmeyen işlemler için async kullanın (log, notification, analytics). Etki: Ana istek akışı bloklanmaz. End-user response time düşer. Backend timeout riski azalır.
Data Manipulation Optimizasyonu	Öneri: Büyük JSON/XML dosyalarında gereksiz parsing yapmayın. Sadece gerekli alanları manipüle edin. Variable kullanarak XPath/JSONPath ile direkt alana erişin. Etki: CPU kullanımı %50-70 azalır. Memory consumption düşer. Throughput artar.
Timeout Tuning	Öneri: Backend servisi average response time'ını ölçün. Timeout'u average + 2x standard deviation olarak ayarlayın. Örnek: Avg: 2s, StdDev: 1s → Timeout: 4s Etki: Gereksiz timeout oluşmaz. Yanıt vermeyen backend'ler hızlı fail eder. Resource leak önlenir.

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	REST API Call politikası ile API Proxy arasındaki fark nedir?	API Proxy: İstemciye sunulan public endpoint. REST API Call: Politika olarak başka bir backend API'sine çağrı yapar. Bir API Proxy içinde REST API Call politikası kullanılabilir. Örnek: İstemci → API Proxy (/payment) → REST API Call → Backend (/charge)
Genel	Aynı API Proxy'de birden fazla REST API Call politikası kullanabilir miyim?	Evet. Farklı condition'larla veya sıralı olarak birden fazla REST API Call politikası kullanabilirsiniz. Örnek: İlk politika authentication, ikinci politika data fetch.
Teknik	Synchronous ve Asynchronous arasındaki fark pratikte nedir?	Synchronous: İstek gönderilir, yanıt beklenir, yanıt işlenir, istemciye dönülür. Total time artar ama kontrol tam. Asynchronous: İstek gönderilir, yanıt beklenmez, hemen istemciye dönülür. Total time düşer ama backend başarı/hata bilgisi alınamaz.
Teknik	Cache'de veri bozulması veya stale data riski var mı?	TTL doğru ayarlanırsa risk minimumdur. TTL sonunda cache temizlenir. Manuel cache clear için Cache Policy kullanın. Critical data için TTL'yi düşük tutun (30-60 saniye).
Kullanım	Test Helper nedir, nasıl kullanılır?	Test Helper, REST API Call için URL oluşturmayı kolaylaştırır. Mevcut API Proxy'leri listeler, seçtiğiniz proxy'nin URL'ini otomatik doldurur. Environment seçimi yapabilirsiniz. ⚙️ ikonuna tıklayarak açılır.
Kullanım	Data Manipulation'da ADD ve REPLACE farkı nedir?	ADD: Yeni bir alan ekler. Örnek: Response JSON'a yeni alan ekle: response.user.fullName = ${user.firstName} + ${user.lastName} REPLACE: Mevcut alanı değiştirir. Örnek: request.body.price değerini ${discounted.price} ile değiştir.
Hata	"PolicyRestApiCallConnectionException" hatası alıyorum. Çözüm?	Backend servisi erişilemiyor. Kontrol: URL doğru mu? Backend ayakta mı? Network firewall var mı? Certificate gerekiyor mu? Timeout çok düşük mü (artırın)?
Hata	Cache çalışmıyor, her çağrıda backend'e gidiyor. Neden?	Kontrol: Cache enabled mi? Capacity ve TTL tanımlı mı? Cache By variable doğru set edilmiş mi? Aynı cache key ile istek geliyor mu? Cache storage type distributed ise cache sunucusu ayakta mı?
Performans	REST API Call politikası performance overhead'i ne kadardır?	Minimal. Ek latency: Data manipulation varsa 5-20ms, yoksa 2ms'den az. Cache aktifse cache hit'te backend çağrısı olmaz, latency %90 düşer. Asynchronous modda overhead neredeyse sıfır.