Minimum Mesaj Uzunluğu (Min. Message Size)

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ış

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

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. Payload Doğrulaması: İstek gövdesi string'e dönüştürülür, ölçülen byte/karakter uzunluğu tanımlanan size değeri ile karşılaştırılır.
4. Karar Verme:
   • Eşleşme Var: Gövde uzunluğu size değerinden büyükse istek normal akışta devam eder.
   • Eşleşme Yok: Gövde boş ya da size değerine eşit/altında ise istek durdurulur ve hata mesajı tetiklenir. Varsayılan hata ERR-026 ve 403 Forbidden'dır.
5. 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ı: size alanı 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: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: 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 5: 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 6: 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 7: 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 8: 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 9: 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.

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 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.