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
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- 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ı?
- XML Şema Değerlendirmesi:
validateAgainstSpec=trueise ilgili API Proxy’nin WSDL tanımlarından şema çekilir; aksi durumda girilenschemaDefinitionListXSD içerikleri vepathForBodyXPath çıktısı kullanılarak XML parser doğrulaması yapılır. - 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.
- 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:
pathForBodyalanı 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:
schemaDefinitionListile birden çok şema segmenti eklenebilir, her birischemaNoile sıralanır vesystemIdile 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:
validateAgainstSpecseç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: 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 4: 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 5: 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 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 = 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 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": "[Default hata mesajı]" }Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" } |
| Adım 8: 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. |
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. |