JSON Şema Doğrulama

İstek gövdelerini JSON Şema tanımlarına göre doğrulayabilir ve uyumsuz talepleri 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 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

1. İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. JSON Şema Doğrulama: pathForBody olarak tanımlanan JSONPath ifadesiyle isteğin doğrulanacak bölümü elde edilir; bölüm, tanımlı tüm JSON schemaDefinitionList girdilerine göre RFC 8259 uyumlu şema doğrulamasından geçirilir.
4. 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.
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

• JSONPath Tabanlı Veri Hedefleme: pathForBody alanı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 pathForBody ifadesi 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, globalPolicyChangedInProxy olayları ü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: 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: 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 5: 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 6: Ş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 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
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 JSON şeması tanımlı. 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 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.