Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) üzerinden gelen isteklerde zorunlu içerik taşınmasını sağlayarak boş veya hatalı gövdeleri engeller.
- Minimum veri boyutu güvence altına alınarak iş kurallarının ihlal edilmesi daha istek girişinde durdurulur.
- Eksik payload nedeniyle backend servislerinde oluşabilecek hataları ve gereksiz kaynak tüketimini azaltır.
- Hata mesajı özelleştirmesiyle istemcilerin minimum gereksinimi hızla anlamasına yardımcı olur.
- Koşul bazlı kullanım sayesinde sadece hassas endpoint’lerde veya belirli istemci segmentlerinde aktif edilir.
Çalışma Prensibi
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- Politika Kontrolü: Minimum Mesaj Boyutu politikası aktif ise, 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ı?
- Payload Doğrulaması: İstek gövdesi string’e dönüştürülür, ölçülen byte/karakter uzunluğu tanımlanan
sizedeğeri ile karşılaştırılır. - Karar Verme:
- Eşleşme Var: Gövde uzunluğu
sizedeğerinden büyükse istek normal akışta devam eder. - Eşleşme Yok: Gövde boş ya da
sizedeğerine eşit/altında ise istek durdurulur ve hata mesajı tetiklenir. Varsayılan hata ERR-026 ve 403 Forbidden’dır.
- Eşleşme Var: Gövde uzunluğu
- Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.
Özellikler ve Yetenekler
Temel Özellikler
- Boş Gövde Engelleme: İstek gövdesi bulunmayan veya beklenen eşiğin altındaki payload’ları otomatik olarak reddeder.
- Minimum Byte Eşiği Doğrulaması:
sizealanı ile tanımlanan en düşük veri boyutunu uygulayarak veri bütünlüğü sağlar. - gRPC Uyumlu Çalışma:
availableForGrpc()desteği sayesinde HTTP ve gRPC mesajlarını aynı kuralla doğrular. - 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
- Koşula Göre Minimum Eşik: Path, method veya header bilgilerine göre farklı minimum boyut politikaları tanımlamaya imkan tanır.
- Hata Mesajı Versiyonlama: EnumParentErrorType.POLICY_MINMESSAGESIZE tabanlı hata mesajları çok dilli ve format uyumlu şekilde yönetilir.
- Kullanım İzleme Entegrasyonu: Policy usage sekmeleriyle politikayı kullanan API Proxy ve grupları merkezi olarak izlenir.
- 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ç |
|---|---|---|---|
| Boş POST Gövdelerini Engelleme | Bazı istemciler POST çağrılarını gövdesiz gönderiyor | size = 1 belirle | Gövdesiz POST istekleri 403 ERR-026 ile reddedilir |
| Zorunlu Alan Kontrolü | JSON kullanıcı kayıtlarında minimum veri olmalı | size = 256 tanımla | 256 byte altındaki JSON istekleri bloklanır, eksik veri tespit edilir |
| gRPC Mesaj Doğrulaması | gRPC hizmeti boş payload aldığında hata veriyor | Politika gRPC’de aktif, size = 512 | Çok küçük gRPC mesajları gateway’de durdurulur |
| Webhook Sağlama | Dış sağlayıcı ara sıra boş webhook gönderiyor | Query Builder’da endpoint koşulu + size = 128 | Sadece hedef webhook rotasında minimum 128 byte şartı uygulanır |
| Sahte Trafik Filtreleme | Bot’lar 0 byte isteklerle sistemi yokluyor | Politika global, size = 64 | Bot trafiği 403 dönüşü alır, log’da kayıt altına alınır |
| Dosya Metadata Kontrolü | Dosya yüklenirken metadata gövdesi boş geliyor | Multipart metadata endpoint’inde size = 1024 | Zorunlu metadata alanı olmayan yüklemeler reddedilir |
| PII Tutarlılığı (opsiyonel) | Kişisel veri içermeyen boş kayıtlar log’a düşüyor | Policy Group içinde size = 512 | Politikayla eşleşmeyen istekler bloklanır, raporlama tutarlılığı 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 Minimum Mesaj Boyutu 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 → Minimum Mesaj Boyutu 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: Production_MinPayload- 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: “Boş JSON POST isteklerini engelle.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Minimum Mesaj Uzunluğu (byte) Değerini Tanımlama | - Minimum Mesaj Uzunluğu (byte) alanına payload için zorunlu alt sınırı girin. - En küçük geçerli değer 1’dir; size değeri > 0 olmalıdır.- Gövde uzunluğu <= size olduğunda istek bloklanacağını unutmayın. |
| Adım 4: Boş Gövde Davranışını Belirleme (Varsa) | - Beklenen alanların gerçekten taşındığından emin olmak için limit değerini örnek isteklere göre belirleyin. - Çok düşük değerler boş payload’ı kaçırabilir, çok yüksek değerler gereksiz engelleme yapabilir. - Test için küçük, canlı için gerçek üretim boyutlarına yakın eşik seçin. |
| Adım 5: Endpoint Bazlı Koşul Tasarlama (Varsa) | - Koşul sekmesinde path, method, header gibi kriterlerle politikayı hedef endpoint’lere sınırlayın. - Farklı minimum değerler için politikayı klonlayıp Policy Group altında gruplayın. - Hassas veri kabul eden rotalarda politikayı daima aktif tutun. |
| 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/admin/*Koşul tanımlamazsa politika her zaman aktif Detaylar için bakabilirsiniz: Koşullar (Conditions) |
| Adım 7: Hata Mesajı Özelleştirme (İsteğe Bağlı) | - Error Message Customization sekmesine gidin. - Erişim reddedildiğinde dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 403, "message": "Permissible Min. Size Policy Validation failed! Permissible min. size of request must be ( {0} ) but found ( {1} ) !" }Özel: { "statusCode": 422, "errorCode": "PAYLOAD_TOO_SMALL", "message": "İstek gövdesi minimum 256 byte olmalıdır." } |
| Adım 8: Kaydetme | - Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir minimum boyut gereksinimi tanımlandı. 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 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 Akışa Politika Ekleme bölümüne bakabilirsiniz.İleri Düzey Özellikler
| Özellik | Açıklama ve Adımlar |
|---|---|
| Dinamik Minimum Değer Yönetimi | - Farklı ortamlar için (Geliştirme, Test, Canlı) ayrı politikalar oluşturun. - Policy Group ile ortam bazlı dağıtım yapın. - Değerleri kullanım istatistiklerine göre periyodik güncelleyin. |
| Payload Sağlamlık Denetimi | - Minimum boyutu, zorunlu alanların toplam uzunluğunu kapsayacak şekilde belirleyin. - Eksik alanları tespit etmek için hata mesajında beklenen/gerçek boyutu yayınlayın. - QA sürecinde politikayı local kopya olarak test edin. |
| Global Politika Senkronizasyonu | - Global politikada değişiklik yapmadan önce fetchUsedProxies çıktısını kontrol edin.- Birden fazla API kullanıyorsa değişiklik öncesi ilgili ekipleri bilgilendirin. - Güncelleme sonrası deploy işlemini tetikleyerek tüm Proxy’leri senkronize edin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Payload Planlama | Kötü: Minimum değeri 0 bırakmak. İyi: Gerçek ortalama payload boyutuna göre eşik tanımlamak. En İyi: Log analizlerine dayanarak eşiği periyodik olarak ayarlamak. |
| Koşul Tasarımı | Kötü: Tüm endpoint’leri tek politikayla yönetmek. İyi: Hassas endpoint’leri ayrı politika ile sınırlandırmak. En İyi: Query Builder ile method/path bazlı koşullar kurgulamak. |
| Ortam Ayrımı | Kötü: Geliştirme ve Canlı için aynı minimum değeri kullanmak. İyi: Geliştirmede toleranslı, Canlı’da sıkı eşik belirlemek. En İyi: Local politikalarla ortam bazlı eşikleri yönetmek. |
| Hata Yönetimi | Kötü: Varsayılan mesajı değiştirmeden istemciyle paylaşmak. İyi: Mesajı Türkçe/İngilizce olarak özelleştirmek. En İyi: İstemcinin beklediği JSON formatında hata kodu ve min/gerçek değer bilgisi sağlamak. |
| Sürüm Kontrolü | Kötü: Değişikliklerden önce yedek almamak. İyi: Export ile manuel yedek oluşturmak. En İyi: Export dosyalarını sürümleyip CI/CD hattına entegre etmek. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Bot Trafik Filtreleme | Minimum boyut şartı ile boş veya sahte istekleri erken bloklayın. |
| Hata Mesajı İçeriği | Hata mesajında sadece beklenen ve mevcut boyutu paylaşın; sistem iç ayrıntıları ifşa etmeyin. |
| Log Tutarlılığı | Reddedilen istekleri güvenlik loguna yazın; kaynak IP, endpoint ve boyut bilgilerini koruyun. |
| Koşul Güvenliği | Koşul tanımlarında geniş wildcard kullanımlarından kaçının; kritik rotalar için özel politika oluşturun. |
| Global Değişiklik Denetimi | Kullanımda olan global politikayı güncellemeden önce etki analizini tamamlayın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Yanlış Eşik Belirleme | Neden kaçınılmalı: Çok düşük değerler boş payload’ı kaçırır. Alternatif: Gerçek istek boyutlarını ölçüp eşik belirleyin. |
| Koşulsuz Uygulama | Neden kaçınılmalı: Tüm endpoint’lerde gereksiz engellemeye yol açabilir. Alternatif: Query Builder ile hedef endpoint’leri seçin. |
| Hata Mesajını Kapatma | Neden kaçınılmalı: İstemci sorunu anlamaz, tekrar eden hatalar oluşur. Alternatif: Minimum/gerçek boyutu açıklayan mesaj sağlayın. |
| Global Güncellemeyi Plansız Yapma | Neden kaçınılmalı: Çoklu API’lerde aynı anda kesinti yaratabilir. Alternatif: Önce test ortamında local politika ile doğrulayın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| İstek Boyutu Ölçümü | Öneri: size değerini gerçek ortalamalara göre belirleyin.Etki: Gereksiz engellemeleri önleyerek throughput’u korur. |
| Loglama Seviyesi | Öneri: Reddedilen istekleri ayrı log kanalında tutun. Etki: Analiz kolaylaşır, ana log’lar şişmez. |
| Policy Zinciri Sırası | Öneri: Minimum boyut kontrolünü zincirde erken konumlandırın. Etki: Küçük payload’lar için gereksiz diğer policy çalışmaları engellenir. |
| Koşul Ön Bellekleme | Öneri: Sık kullanılan koşulları Query Builder’da optimize edin. Etki: Koşul değerlendirme süresi azalır. |
| gRPC Mesajları | Öneri: gRPC çağrılarında beklenen seri hale getirilmiş boyutu dikkate alın. Etki: gRPC performansı stabil kalır. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Minimum değer 0 olabilir mi? | Hayır. size alanı en az 1 olmalı; 0 değeri boş payload’ları durdurmaz. |
| Genel | Politikayı sadece belirli endpoint’lerde kullanabilir miyim? | Evet, Query Builder koşullarıyla hedef endpoint, method veya header temelli filtreleme yapılabilir. |
| Teknik | Boyut ölçümü byte mı karakter mi? | Gateway gövdeyi string olarak değerlendirir; tipik senaryoda karakter uzunluğu varsayılır, UTF-8’de karakter=byte varsayımı geçerlidir. |
| Teknik | gRPC mesajlarında nasıl çalışır? | availableForGrpc() true olduğu için serialize edilmiş mesajın uzunluğu kontrol edilir; eşik altındaysa istek bloklanır. |
| Kullanım | Varsayılan hata kodu nedir? | 403 Forbidden ve ERR-026 kodu döner; Error Message sekmesinden özelleştirilebilir. |
| Kullanım | Global politikayı lokal kopyaya çevirebilir miyim? | Detay sayfasındaki Localize butonu politikayı local kopya olarak çoğaltmanızı sağlar; minimum değer ihtiyaca göre güncellenebilir. |