Maksimum Mesaj Uzunluğu (Max. Message Size)

Gelen istek gövdesinin byte cinsinden üst sınırını denetleyerek aşımı engelleyebilirsiniz

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 isteklerin gövde büyüklüğünü sınırlandırarak sistem kaynaklarını korur.
• Yüksek boyutlu isteklerin servis performansını düşürmesini ve beklenmedik zaman aşımı sorunlarını engeller.
• Tanımlı güvenilir sınırların dışında kalan veri transferlerini erken aşamada durdurup backend servislerini korur.
• İsteğe bağlı hata mesajı özelleştirme ile istemci tarafında hızlı hata ayıklamayı destekler.

​

Ç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ü: Maksimum 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. Mesaj Boyutu Ölçümü: İstek gövdesinin byte cinsinden uzunluğu okunur ve tanımlanan size değeri ile karşılaştırılır.
4. Karar Verme:
   • Eşleşme Var: İstek boyutu tanımlanan limitten küçükse iletim devam eder.
   • Eşleşme Yok: Boyut limiti >= size olduğunda istek engellenir ve yapılandırılmış hata mesajı döner.
5. Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür. Varsayılan olarak 403 ERR-027 kodu gönderilir.

​

Özellikler ve Yetenekler

​

Temel Özellikler

• Byte Bazlı Mesaj Kısıtlama: İstek gövdesi uzunluğunu byte cinsinden ölçerek tanımlanan limite ulaşıldığında işlemi durdurur.
• Anlık Engelleme Mekanizması: Limit aşımı tespit edilir edilmez zinciri keserek backend servislerine yük binmesini önler.
• gRPC Uyumlu Doğrulama: availableForGrpc() desteği sayesinde hem HTTP hem gRPC çağrılarında aynı kural seti kullanılabilir.
• 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 Limit Belirleme: Query Builder ile belirli endpoint, header, method veya kullanıcı segmentlerine özel farklı limitler tanımlanabilir.
• Hata Mesajı Lokalizasyonu: Özel hata kodu ve mesajlarıyla istemci tarafında anlaşılır geri bildirim sağlanır, çoklu dil desteğiyle uyumludur.
• Politika Kullanım Takibi: Kullanıldığı API Proxy’ler, Proxy Group’lar ve Policy Group’lar tek ekran üzerinden izlenebilir.
• 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ç
Büyük JSON İstek Engelleme	Mikroservis 1 MB üzeri JSON istekleri işleyemiyor	size = 1048576 tanımla	1 MB ve üzeri istekler 403 ERR-027 dönüşüyle bloke edilir
Dosya Yükleme Kısıtı	API Proxy yalnızca metadata kabul ediyor	size = 65536 değerine çek	64 KB üzerindeki multipart gövdeler reddedilir
gRPC Çağrılarında Limit	gRPC isteğinde beklenmedik büyük payload geliyor	Policy’i gRPC için aktive et, limit 200 KB	Büyük gRPC mesajları Gateway’de durdurulur
Çevrimdışı Koşullu Limit	Sadece /legacy/* endpoint için 200 KB sınırı gerekiyor	Query Builder’da Path koşulu ekle, size = 204800	Diğer endpointler etkilenmeden legacy rotalar sınırlandırılır
Test Ortamı Farklı Limiti	Test API’si 512 KB, Canlı 256 KB olmalı	Testte local politika size = 524288, canlıda global size = 262144	Ortama özgü limitler sorunsuz uygulanır
DDoS Önleme	Saldırı sırasında binlerce büyük istek geliyor	Policy’i global olarak aktive et, limit 100 KB	Kaynak tüketimi artmadan Gateway 403 ile yanıtlar
Mesaj Boyutu Uyarısı (opsiyonel)	Limit aşımında özel hata kodu isteniyor	Error Message tabında errorCode=PAYLOAD_LIMIT tanımla	İstemci özel hata kodunu loglayarak müdahale eder

​

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 Maksimum 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 → Maksimum 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_MaxPayload - 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: “JSON POST istekleri için 512 KB üst sınır.” - 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: Maksimum Mesaj Uzunluğu (byte) Değerini Belirleme	- Maksimum Mesaj Uzunluğu (byte) alanına istek gövdesinin izin verilen üst sınırını girin. - Minimum değer 1’dir; değer >= 1 olmalıdır. - Limitin kendisi de dahil (>= size) engelleneceğini unutmayın.
Adım 5: Global Politika Olarak Paylaşma (İsteğe Bağlı)	- Add to Global anahtarını aktif ederek politikayı tüm projeler için kullanılabilir hale getirebilirsiniz. - Lokal çalışma sırasında devre dışı bırakarak sadece ilgili API’de kullanabilirsiniz.
Adım 6: Kullanımda Olan Politikayı Yeniden Adlandırma (İsteğe Bağlı)	- Var olan global politika üzerinde değişiklik yaparken kullanımda olan API Proxy’ler için sistem uyarı verir. - Yeni isim veya ID üretmek gerektiğinde politikayı kopyalayıp local olarak kaydedin.
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 Max. Size Policy Validation failed! Permissible max. size of request must be ( {0} ) but found ( {1} ) !" } Özel: { "statusCode": 403, "errorCode": "PAYLOAD_LIMIT", "message": "İstek gövdesi 256 KB sınırını aştı." }
Adım 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir limit değeri 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
Koşula Bağlı Limit Farklılaştırma	- Query Builder’da method, path veya header bazlı koşullar tanımlayın. - Her koşul için farklı size değeri içeren klon politikalar oluşturun. - Yüksek hacimli endpoint’lerde daha düşük limitlerle DoS riskini azaltın.
gRPC Mesaj Denetimi	- availableForGrpc() sayesinde aynı politikayı gRPC servislerine atayın. - gRPC mesaj büyüklükleri string uzunluğu üzerinden doğrulanır. - Gateway katmanında erken kesme yapılarak backend gRPC servisleri korunur.
Global Politika Kullanım Analizi	- Detay sayfasındaki Usage sekmeleri ile politika kullanım haritasını inceleyin. - Yoğun kullanılan API Proxy’lerde limit değişiminden önce etki analizini yapın. - Deploy sonrası listeye dönerek güncel kullanım durumunu doğrulayın.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Payload Planlama	Kötü: Limit değeri servis kapasitesinden yüksek bırakmak. İyi: Ortalama payload boyutuna göre limit belirlemek. En İyi: Gerçek üretim izlerine göre periyodik limit güncellemesi yapmak.
Ortam Yönetimi	Kötü: Geliştirme ve Canlı aynı limiti kullanmak. İyi: Test ortamında daha yüksek tolerans tanımak. En İyi: Ortam bazlı local politikalar tanımlayarak farklı limitler uygulamak.
Koşul Modelleme	Kötü: Tüm istekleri tek politikaya bağlamak. İyi: Hassas endpoint’ler için ayrı politika oluşturmak. En İyi: Query Builder ile method/path bazlı limitleri ayrıştırmak.
Hata Mesajı Yönetimi	Kötü: Varsayılan mesajı tüm istemcilerle paylaşmak. İyi: Mesajı Türkçe ve İngilizce olarak özelleştirmek. En İyi: İstemcinin beklediği formatta (JSON/Plain) hata mesajı üretmek.
Sürüm Kontrolü	Kötü: Değişiklikleri kaydetmeden önce export almamak. İyi: Her büyük değişiklik sonrası export etmek. En İyi: Export dosyalarını versiyonlayıp CI/CD sürecine dahil etmek.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
DoS Koruması	Limitleri düşük tutarak büyük payload’ların kaynak tüketmesini engelleyin; anlık saldırı durumunda limitleri düşürmeyi değerlendirin.
Hata Bilgisi Sızması	Özel hata mesajı verirken sistem iç detaylarını paylaşmayın; sadece limit ve tespit edilen boyutu belirtin.
Log Yönetimi	Limit aşımını güvenlik loguna yazın; istemci IP ve endpoint bilgilerini koruyun.
Koşul Güvenliği	Koşullar oluştururken wildcard kullanımlarını minimumda tutun; hassas rotaları ayrı politikalarla yönetin.
gRPC Kanal Koruması	Büyük mesajları kabul eden gRPC servislerinde politikayı zorunlu kılın; saldırı yüzeyini daraltın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Aşırı Düşük Limitler	Neden kaçınılmalı: Gerçek kullanıcı istekleri de engellenebilir. Alternatif: Ortalama payload ölçümlerine göre limit tanımlayın.
Koşulsuz Global Limit	Neden kaçınılmalı: Tüm API Proxy’ler aynı limiti paylaşır, esneklik azalır. Alternatif: Politika grupları veya local politikalarla farklılaştırın.
Log Tutmamak	Neden kaçınılmalı: Limit aşımının kaynağı tespit edilemez. Alternatif: Gateway loglarına hata kodu ve payload boyutunu ekleyin.
Import Sonrası Doğrulama Yapmamak	Neden kaçınılmalı: Yanlış limit değerleri Canlı Ortam’da kalabilir. Alternatif: Import sonrası değerleri ve koşulları manuel kontrol edin.

​

Performans İpuçları

Kriter	Öneri / Etki
Gateway Bellek Kullanımı	Öneri: Limit değerini servis kapasitesine göre ayarlayın. Etki: Gereksiz büyük payload’lar parse edilmeden engellenir.
Throughput	Öneri: Limit aşımında hata mesajını hafif tutun. Etki: Ağ üzerinden geri dönüş süresi kısalır.
İzleme	Öneri: Limit aşım oranını metrik olarak toplayın. Etki: Anormallikler erken fark edilir.
Koşul Evaluasyonu	Öneri: Query Builder koşullarını optimize edin, gereksiz regex kullanmayın. Etki: İstek başına değerlendirme süresi düşer.
Cache Entegrasyonu	Öneri: Limit aşımı yapan istemcileri kısa süreli Cache ile takip edin. Etki: Tekrarlayan ihlallerde ek koruma katmanı sağlar.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Maksimum Mesaj Boyutu politikası neyi kısıtlar?	İstek gövdesinin byte cinsinden uzunluğunu sınırlar; limit aşılırsa istek 403 ile reddedilir.
Genel	Limit değeri hangi formatta girilmeli?	Değer decimal formatta ve byte cinsinden girilir; minimum 1 olmalıdır.
Teknik	Limit eşit olduğunda istek kabul edilir mi?	Hayır. Gövde uzunluğu >= size olduğunda politika isteği engeller.
Teknik	gRPC çağrılarında da çalışır mı?	Evet, availableForGrpc() özelliği sayesinde gRPC mesajları da doğrulanır.
Kullanım	Farklı endpoint’ler için farklı limitler nasıl tanımlanır?	Query Builder’da endpoint bazlı koşullar oluşturup her koşul için ayrı politika atayın.
Kullanım	Varsayılan hata mesajını nasıl değiştirebilirim?	Error Message Customization sekmesinden durum kodu, hata kodu ve mesaj alanlarını düzenleyebilirsiniz.