Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) üzerinden gelen JSON tabanlı çağrıların beklenen veri sözleşmesine uyup uymadığını otomatik olarak kontrol ederek hatalı verilerin arka uç sistemlere ulaşmasını engeller.
- JSONPath (
pathForBody) ifadesi üzerinden isteğin belirli bölümlerini hedefleyerek kapsamlı fakat esnek doğrulama senaryoları kurulmasına imkan tanır. - Birden fazla JSON Şema sürümünü aynı politika altında yöneterek farklı endpoint, versiyon veya istemci tiplerine göre uyarlanabilir doğrulama akışları sağlar.
- Koşul motoru ve hata mesajı özelleştirmesiyle, doğrulamanın hangi durumlarda tetikleneceğini ve istemcilere hangi mesajların döneceğini merkezi olarak kontrol eder.
Ç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ü: JSON Ş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ı?
- JSON Şema Doğrulama:
pathForBodyolarak tanımlanan JSONPath ifadesiyle isteğin doğrulanacak bölümü elde edilir; bölüm, tanımlı tüm JSONschemaDefinitionListgirdilerine göre RFC 8259 uyumlu şema doğrulamasından geçirilir. - Karar Verme:
- Eşleşme Var: En az bir şema ile uyum sağlanırsa istek akışa devam eder ve hedef API Proxy cevabı döndürülür.
- Eşleşme Yok: Hiçbir şema ile uyum sağlanamazsa politika akışı sonlandırır ve tanımlı hata mesajı/HTTP kodu ile istemci bilgilendirilir.
- 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
- JSONPath Tabanlı Veri Hedefleme:
pathForBodyalanıyla isteğin hangi bölümünün doğrulanacağı seçilir; varsayılan$.ifadesi tam gövdede çalışır. - Çoklu JSON Şema Desteği:
schemaDefinitionListüzerinden birden fazla şema eklenir, her biri otomatik numaralandırılır ve farklı kullanım senaryolarına atanabilir. - Gömülü JSON Editörü: Şema tanımları, syntax vurgulu Apinizer code editor bileşeni üzerinde düzenlenerek doğruluk ve okunabilirlik artırılır.
- 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
- JSONPath Test Modülü: Test Transformation Data bileşeniyle
pathForBodyifadesi gerçek veriler üzerinde çalıştırılarak doğru alanın hedeflendiği anında doğrulanır. - Şema Sürümleme Stratejisi: Her yeni şema kaydı için otomatik
schemaNoüretimi sayesinde farklı versiyonlar izlenebilir ve gerektiğinde hızlıca devreye alınabilir. - Global/Lokal Politika Akışı: Global politikalar lokal politikalara dönüştürülebilir,
globalPolicyChangedInProxyolayları üzerinden kullanıcı etkileşimi sağlanır. - 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ç |
|---|---|---|---|
| Giriş Gövdesi Doğrulama | Public API’ye gelen JSON kullanıcı kaydı isteği farklı formatlarda geliyor. | pathForBody=$.; tek bir kayıt şeması eklenir; zorunlu property tanımları yapılır. | Uymayan kayıtlar 403 döner, geçerli kayıtlar backend’e iletilir. |
| Versiyonlu Şema Yönetimi | Aynı Endpoint hem v1 hem v2 gövdelerini kabul ediyor. | İki farklı şema tanımı eklenir; her biri ilgili schemaNo ile versiyonlanan şema tanımlarını içerir. | İstek hangi şemaya uyuyorsa kabul edilir, diğerleri reddedilir. |
| Parçalı Doğrulama | Büyük JSON içerisinde sadece payload.data alanı denetlenmeli. | pathForBody=$.payload.data; ilgili şema sadece bu segment için yazılır. | Yalnızca hedef alan doğrulanır, diğer alanlar serbest kalır. |
| Opsiyonel Alan Kontrolü | Bazı alanlar isteğe bağlı ancak formatları doğru olmalı. | Şema içerisinde anyOf kullanılır; editor üzerinden koşullar tanımlanır. | Opsiyonel alan geldiğinde format kontrol edilir, yoksa istek kabul edilir. |
| Partner Bazlı Kısıtlama | Header’da gelen X-Partner değerine göre farklı şema uygulanacak. | Query Builder’da header koşulu tanımlanır; uygun partner için şema eklenir. | Sadece koşula uyan istekler doğrulamaya girer; diğerleri politikadan etkilenmez. |
| Test Ortamı Güvencesi | Geliştirme ortamına özel detaylı validasyon istendi. | Global politikanın lokali oluşturulur; pathForBody ve şemalar test gereksinimlerine göre güncellenir. | Test API Proxy’si üzerinde sıkı doğrulama yapılır, canlı ortam etkilenmez. |
| JSONPath Deneme & Onay (opsiyonel) | Yeni JSONPath ifadesinin hedefi doğrulanmak isteniyor. | Test Data Transformation modülü açılır, örnek veri ile path test edilir. | Yanlış ifade uyarı olarak gösterilir, doğru ifade kaydedilir. |
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 JSON Ş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 → JSON Şema Doğrulama Politikası 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_JSONSchemaValidation- 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ş servisinde JSON gövdesini doğrular” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: JSONPath Tanımı | pathForBody alanına JSONPath ifadesini girin.- Varsayılan $. tüm gövdeyi doğrular.- Parçalı doğrulama için örn. $.payload.data kullanın.- Gerekirse aynı ekrandan JSONPath testini başlatın. |
| Adım 4: JSON Şema Tanımları | Add butonuyla yeni şema paneli ekleyin. - Her panel otomatik JSON n başlığı ve schemaNo alır.- Editor içinde geçerli JSON Şema (Draft 4+) tanımını yapın. - Şemayı kaldırmak için çöp kutusu ikonunu kullanın; numaralandırma otomatik güncellenir. |
| Adım 5: Şema Test ve Önizleme | Test Data Transformation JSONPath butonuyla örnek veri üzerinde pathForBody ifadesinin doğru segmenti seçtiğini doğrulayın.- Editor üzerinden JSON şemanızın Apinizer code editor’ünde biçimlendiğinden emin olun. |
| 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 |
| 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 JSON şeması tanımlı. 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 Politikayı API’ye Bağlama bölümüne bakabilirsiniz.İleri Düzey Özellikler
| Özellik | Açıklama ve Adımlar |
|---|---|
| JSON Şema Versiyonlama Yönetimi | - Her Add işleminde otomatik artan schemaNo değerini kullanarak şema sürümlerini sıralayın.- Eski şemaları pasif ortamlarda saklayın, gerekirse yeniden etkinleştirin. - Export öncesi sürümleri numaralarına göre dokümante edin. |
| Global Politika Lokalizasyonu | - Detay ekranındaki Localize butonuyla global politikayı kopyalayın. - Lokal politika üzerinde pathForBody veya şema içeriklerini API’ye özel düzenleyin.- Lokal politikayı ilgili API Proxy üzerinde aktif edin. |
| Koşullu Şema Uygulama Mimarisi | - Query Builder’da header veya endpoint bazlı koşullar oluşturun. - Koşulu sağlayan istekleri farklı şema setleriyle eşleştirin. - Kullanım raporlarını inceleyerek hangi koşulların tetiklendiğini takip edin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Şema Yapılandırması | Kötü: JSON şemayı boş bırakarak yalnızca presence kontrolü yapmak. İyi: Temel zorunlu alanları ve tipleri tanımlamak. En İyi: Enum, pattern ve format kurallarıyla zenginleştirilmiş tam kapsamlı şema kullanmak. |
| JSONPath Yönetimi | Kötü: pathForBody alanını yanlış JSONPath ile bırakmak.İyi: $. kullanarak tüm gövdeyi doğrulamak.En İyi: Test Transformation ile doğrulanan, minimal veri segmentini hedefleyen JSONPath kullanmak. |
| Hata Mesajı İletişimi | Kötü: Varsayılan mesajla işletme kullanıcılarını bilgilendirmemek. İyi: Genel hata kodu ve mesajını Türkçe özelleştirmek. En İyi: Hata kodu, iz sürme numarası ve kullanıcı aksiyon önerisi içeren yapılandırma yapmak. |
| Koşul Tasarımı | Kötü: Koşul tanımlamadan politikayı tüm isteklerde çalıştırmak. İyi: Endpoint bazlı koşullar eklemek. En İyi: Ortam, istemci ve yük tipine göre birleşik koşullar oluşturarak yalnızca gerekli akışlarda doğrulama yapmak. |
| Versiyon Yönetimi | Kötü: Eski şemaları silmeden yeni sürümü üzerine yazmak. İyi: Yeni şemayı ekleyip eskisini pasif hale getirmek. En İyi: Şema sürümlerini export edip etiketlemek, test ortamında doğruladıktan sonra canlıya almak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Veri Doğruluğu | Şema sadece tip doğrulamasıyla sınırlı kalmamalı; minimum/maximum, pattern gibi kurallarla kötü niyetli girişleri engelleyin. |
| Hata Mesajı Maskelenmesi | İstemcilere dönen mesajlarda iç sistem detaylarını paylaşmayın; hassas alan adları veya şema içeriğini sızdırmayın |
| Global Politika Değişiklikleri | Global politikayı güncellemeden önce kullanılan tüm API Proxy listesini inceleyin; değişikliklerin olası etkisini değerlendirin. |
| Import Kontrolleri | Dışarıdan gelen ZIP dosyalarını yalnız güvenilir kaynaklardan alın; import sırasında isim çakışmalarını manuel doğrulayın. |
| Audit ve Loglama | Doğrulama hatalarını API Gateway loglarında izleyin; anomali tespiti için hata kodlarını SIEM’le entegre edin. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Eksik Şema Tanımı | Neden kaçınılmalı: Boş veya eksik şema, doğrulama mekanizmasını etkisiz bırakır. Alternatif: Minimum validasyon kurallarını ekleyip zamanla genişletin. |
| Doğrulanmamış JSONPath | Neden kaçınılmalı: Yanlış path ifadesi nedeniyle politika hiç tetiklenmeyebilir. Alternatif: Kayıt olmadan önce Test Transformation ile path’i doğrulayın. |
| Kontrolsüz Global Değişiklik | Neden kaçınılmalı: Global politikada yapılan değişiklikler tüm API’leri etkileyerek beklenmeyen kesintilere yol açabilir. Alternatif: Önce lokal kopyada test edin ve onay sonrası canlıya alın. |
| Şema Silme Sonrası Export Almamak | Neden kaçınılmalı: Geri dönüş için referans kalmaz, audit izleri kaybolur. Alternatif: Şema silmeden önce politikayı export edin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Şema Boyutu | Öneri: Şemaları mümkün olduğunca sade tutun, gereksiz allOf/anyOf kombinasyonlarını azaltın.Etki: Daha hızlı doğrulama ve düşük CPU tüketimi. |
| JSONPath Karmaşıklığı | Öneri: Karmaşık path ifadelerinde joker karakterleri minimal kullanın. Etki: JSON seçimi hızlanır, gecikme azalır. |
| Çoklu Şema Kontrolü | Öneri: Birden fazla şema gerekiyorsa önce en sık kullanılanı liste başına yerleştirin. Etki: Erken eşleşme ile doğrulama süresi kısalır. |
| Koşul Filtreleme | Öneri: Politika gereksiz isteklerde çalışmaması için Query Builder koşullarını optimize edin. Etki: Gateway kaynaklarının verimli kullanılması. |
| Ön Prod Testleri | Öneri: Canlıya almadan önce aynı yükle test ortamında sonuçları ölçün. Etki: Canlı ortamda performans sürprizi yaşanmaz. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Bu politika XML gövdelerini doğrular mı? | Hayır, yalnızca JSON içerikleri doğrulanır; XML için ayrı politika kullanmalısınız. |
| Genel | Varsayılan hata mesajını değiştirmek zorunlu mu? | Hayır, varsayılan mesaj kullanabilirsiniz ancak kullanıcı deneyimi için özelleştirme önerilir. |
| Teknik | JSON Şema hangi draft sürümünü destekliyor? | Apinizer editörü Draft 4 ve üzeri JSON Şema sözdizimini destekler; geçerli JSON olması yeterlidir. |
| Teknik | pathForBody boş bırakılırsa ne olur? | Varsayılan $. uygulanır ve tüm istek gövdesi doğrulamaya dahil edilir. |
| Kullanım | Aynı politikayı birden fazla API Proxy’de kullanabilir miyim? | Evet, global politika olarak tanımlandığında tüm API Proxy’lere bağlanabilir. |
| Kullanım | Lokal politikaya dönüştürdüğümde global sürüm etkilenir mi? | Hayır, lokal kopya bağımsızdır; değişiklikler global politikaya yansımaz. |