XML Şema Doğrulama

Gelen XML gövdesini tanımlı XSD veya WSDL şemalarına göre kontrol ederek tutarsız istekleri 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?

• Gelen SOAP veya REST tabanlı XML isteklerinin yapısal bütünlüğünü sağlamak, backend servislerine hatalı veri ulaşmasını önlemek.
• API Proxy (API Vekil Sunucusu) seviyesinde WSDL veya XSD şemalarıyla uyumluluk zorunluluğu getirerek entegrasyon kalite standartlarını yükseltmek.
• Koşul bazlı tetikleme ile yalnızca belirli endpoint veya header kombinasyonlarında XML şema doğrulaması yaparak esnek politika yönetimi sunmak.
• Özel hata mesajları sayesinde istemci tarafının hatalı şemayı hızlıca düzeltmesini desteklemek.

​

Ç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ü: XML Şema Doğrulama 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. XML Şema Değerlendirmesi: validateAgainstSpec=true ise ilgili API Proxy’nin WSDL tanımlarından şema çekilir; aksi durumda girilen schemaDefinitionList XSD içerikleri ve pathForBody XPath çıktısı kullanılarak XML parser doğrulaması yapılır.
4. Karar Verme:
   • Eşleşme Var: İstek şemaya uygunsa işlem zinciri devam eder, backend hedefe yönlendirme yapılır.
   • Eşleşme Yok: XML yapısı şemaya uymuyorsa politika isteği durdurur ve özelleştirilebilir hata çıktılarını döndürü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

• XPath Tabanlı Gövde Seçimi: pathForBody alanı sayesinde SOAP Body içinden doğrulanacak düğüm seçilir; boş bırakılırsa tüm gövde incelenir.
• Çoklu XSD Yönetimi: schemaDefinitionList ile birden çok şema segmenti eklenebilir, her biri schemaNo ile sıralanır ve systemId ile ayırt edilir.
• İsim Çakışması Önleme: Politika adı kaydedilmeden önce proje içinde benzersizlik kontrolünden geçer, kullanıcıya anlık geri bildirim sağlar.
• 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

• WSDL Entegrasyonu: validateAgainstSpec seçildiğinde, WSDL’den türetilen XML tipleri otomatik kullanılır ve harici XSD girişi gerektirmez.
• XPath Test Çalıştırıcısı: “Test Data Transformation” bileşeni XPath ifadesinin hedef düğümü doğru seçip seçmediğini anlık olarak doğrular.
• Şema Versiyonlama Stratejileri: Aynı politika içinde farklı schemaDefinitionList öğeleri tutularak kademeli geçiş veya geri dönüş planlanabilir.
• 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ç
SOAP Sipariş Doğrulama	Üçüncü parti SOAP servisi hatalı XML gönderiyor	pathForBody=//*[local-name()='Order'], WSDL doğrulaması kapalı, ilgili XSD ekleniyor.	Şemaya uymayan istek 400 ile bloklanır, hizmet kesilmez.
Entegrasyon Testi	Test ortamında sık değişen XSD sürümleri mevcut	Bir politika içinde birden fazla schemaDefinitionList versiyonu tutuluyor.	Aktif şema güncellenirken eski kayıt saklanır, rollback mümkündür.
Ürün Kataloğu Servisi	Sadece /product/* endpoint’lerinde doğrulama gerekiyor	Condition: Path=/product/*, özel XSD ekleniyor.	Diğer endpoint’ler etkilenmeden ürün API’leri için doğrulama devrede.
WSDL Bazlı Banka Entegrasyonu	Bankanın sağladığı WSDL güncel tutuluyor	validateAgainstSpec=true, politika global tanımlanıyor.	Yeni WSDL yayımlandığında yeniden deploy edilerek doğrulama güncellenir.
XML Gövde Kırpma	Büyük SOAP body içinde tek alan kritik	pathForBody=//*[local-name()='PaymentRequest'] giriliyor.	Sadece ödeme isteği düğümü doğrulanır, performans artar.
Global Politika Paylaşımı	Birden çok API aynı XSD’yi kullanıyor	Politika global oluşturulup Policy Group ile paylaşılıyor.	Tüm ilgili API Proxy’lerde aynı doğrulama uygulanır.
Bölgesel Uyumluluk (opsiyonel)	Sadece AB kullanıcılarının verisi kontrol edilecek	Condition: Header=X-Region, Equals=EU.	AB istekleri şemaya göre doğrulanır, diğerleri bypass edilir.

​

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 XML Şema Doğrulama 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 → XML Şema Doğrulama 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_XMLSchema - 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: “Sipariş akışında XML şema doğrulaması yapar.” - 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: XPath Yapılandırması	- pathForBody alanına doğrulanacak XML düğümünü hedefleyen XPath ifadesini girin. - Tam gövde doğrulaması için boş bırakın veya / kullanın. - XPath doğruluğunu test etmek için Test Data Transformation butonunu kullanabilirsiniz.
Adım 5: WSDL Şeması Kullanımı (Varsa)	- validateAgainstSpec seçeneğini işaretleyerek politikayı bağlı WSDL şemasına göre çalıştırın. - İşaretlendiğinde manuel XSD giriş alanları gizlenir ve bakım yükü azalır.
Adım 6: XSD Şema Tanımları (Varsa)	- validateAgainstSpec kapalıysa Add butonuyla schemaDefinitionList öğeleri ekleyin. - Her öğe için XML şema içeriğini düzenleyin ve gerekiyorsa systemId alanı ile dış referanslar belirtin. - Sıralama schemaNo alanıyla otomatik güncellenir.
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 = Canlı Ortam - 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": "[Default hata mesajı]" } Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" }
Adım 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir XSD tanımı veya WSDL seçimi 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 Akışa Politika Ekleme bölümüne bakabilirsiniz.

​

İleri Düzey Özellikler

Özellik	Açıklama ve Adımlar
WSDL Tabanlı Otomatik Şema Güncelleme	- validateAgainstSpec etkinleştirilir. - API Proxy deploy öncesi WSDL yeniden içeri aktarılır. - Politika deploy edilerek yeni şema yayına alınır.
Çoklu XSD Segmenti Kullanımı	- Birden fazla schemaDefinitionList öğesi eklenir. - Her öğeye açıklayıcı systemId yazılır. - Test ortamında her şema için doğrulama yapılır.
XPath Doğrulama Testi	- Test butonu ile örnek XML yüklenir. - XPath sonucu görüntülenir. - Uygun düğüm seçimi teyit edildikten sonra politika kaydedilir.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
XPath Yönetimi	Kötü: Karmaşık ve belirsiz XPath kullanmak. İyi: XPath’i tek bir hedef düğüm için yazmak. En İyi: XPath’i versiyonlu olarak dokümante edip test aracıyla doğrulamak.
XSD Sürümleme	Kötü: XSD güncellendiğinde eski sürümü silmek. İyi: Eski sürümü dışa aktarıp saklamak. En İyi: Politika Export + Git repo kombinasyonu ile sürüm takibi yapmak.
WSDL Senaryoları	Kötü: WSDL değişince politikayı el ile güncellemeyi unutmak. İyi: WSDL değişikliklerini change log ile izlemek. En İyi: CI/CD pipeline’da WSDL diff tespiti ve otomatik politika deploy süreci kurmak.
Hata Mesajları	Kötü: İstemciye genel hata mesajı döndürmek. İyi: Hata kodunu belirtmek. En İyi: XPath ve şema adıyla birlikte düzeltme önerisi içeren yapılandırılmış JSON döndürmek.
Koşul Tanımları	Kötü: Politikanın her istekte çalışmasına izin verip gereksiz yük oluşturmak. İyi: Temel filtreler eklemek. En İyi: Ortam, endpoint ve header kombinasyonlarını Query Builder ile optimize etmek.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Şema Kaynağı Güvenliği	XSD dosyalarının güvenilir kaynaklardan alındığından emin olun, imza veya checksum doğrulaması kullanın.
WSDL Doğrulama	WSDL güncellemelerini sadece yetkili kullanıcıların yapmasına izin verin, değişiklikleri audit log’larda takip edin.
Politika İzinleri	Global politikaları düzenleme yetkisini sınırlı tutun, RBAC kontrollerini gözden geçirin.
Hata Mesajı İçeriği	Hata mesajlarında iç sistem detaylarını paylaşmayın, sadece düzeltmeye yardımcı olacak minimum bilgiyi verin.
Export/Import Süreci	Export edilen ZIP dosyalarını şifreli depolayın, import öncesi içerik kontrolü yapın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Şemasız Yayın	Neden kaçınılmalı: Şema olmadan politika anlamsız kalır. Alternatif: En az bir XSD tanımı ekleyin veya WSDL seçeneğini aktif edin.
Aşırı XPath Derinliği	Neden kaçınılmalı: Karmaşık XPath performansı düşürür ve bakımını zorlaştırır. Alternatif: XML yapısını sadeleştirip daha basit XPath kullanın.
Geliştirme Ortamında Pasif Bırakma	Neden kaçınılmalı: Üretim öncesi hatalar fark edilmeyebilir. Alternatif: Geliştirme ve testte de aktif tutup otomasyon testlerine ekleyin.
Kontrolsüz WSDL Güncellemesi	Neden kaçınılmalı: Yeni WSDL istekleri beklenmedik şekilde reddedebilir. Alternatif: Güncelleme öncesi regression testleri çalıştırın ve sürüm notu hazırlayın.

​

Performans İpuçları

Kriter	Öneri / Etki
XPath Karmaşıklığı	Öneri: Daha kısa ve doğrudan XPath ifadeleri kullanın. Etki: Parser süresi kısalır, gecikme azalır.
Şema Boyutu	Öneri: Gereksiz yorum satırlarını ve boşlukları kaldırın. Etki: Bellek tüketimi ve yükleme süresi düşer.
Şema Sayısı	Öneri: İlgili XSD’leri tek dosyada birleştirmek yerine modüler tutun. Etki: Değişiklik izolasyonu ve cache yönetimi kolaylaşır.
Koşul Filtreleme	Öneri: Politikanın sadece gerekli endpoint’lerde çalışmasını sağlayın. Etki: Gereksiz doğrulama maliyeti ortadan kalkar.
Test ve İzleme	Öneri: Politika çalışmasını Apinizer metrikleriyle izleyin. Etki: Performans sorunları erken tespit edilir ve optimize edilir.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Politika sadece XML içerikleri mi doğrular?	Evet, politika XML formatındaki gövdeleri XSD veya WSDL şemalarına göre değerlendirir. JSON veya diğer formatlar için farklı politikalar kullanılmalıdır.
Genel	validateAgainstSpec ne zaman tercih edilmeli?	API Proxy WSDL dosyasını güncel tuttuğunuz ve manuel XSD yönetimini azaltmak istediğiniz senaryolarda bu seçenek önerilir.
Teknik	XPath boş bırakılırsa ne olur?	Politika tüm XML gövdesini doğrulamaya çalışır; büyük gövdelerde performans etkisi olabilir.
Teknik	Şema yüklenemediğinde hangi hata döner?	500 Internal Server Error kodu ile şema değerlendirme hatası bildirimi yapılır ve detay log’larda tutulur.
Kullanım	Politika birden fazla API Proxy’de paylaşılabilir mi?	Global olarak tanımlandığında Policy Group veya Proxy Group aracılığıyla birden fazla API Proxy’ye atanabilir.
Kullanım	Hata mesajını farklı ortamlarda nasıl özelleştirebilirim?	Error Message Customization sekmesinde ortam bazlı şablonlar oluşturabilir, Condition bölümüyle ortam değişkenlerine göre farklı politikalar tetikleyebilirsiniz.