JSON Dönüştürme

JSON mesajlarını JOLT ya da JSON→XML dönüştürme ile hedef servise uyumlu hale getirebilirsiniz

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) ile entegrasyonda gelen JSON gövdelerini hedef mikroservisin beklediği şemaya dönüştürerek uyumluluk sağlar.
• Aynı politikayla birden fazla istemcinin üretip gönderdiği JSON formatlarını tek tip hale getirerek bakım maliyetini azaltır.
• JSON içeriklerini XML çıktısına dönüştürerek sadece XML kabul eden legacy Endpoint sistemleriyle köprü kurar.
• Koşullara göre çalıştırılarak belirli tenant, versiyon veya payload içeriğine göre dönüşüm senaryolarını dinamikleştirir.

​

Ç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 Dönüştürme 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 Dönüşüm Kontrolü: transformationType alanı incelenir. JSON2JSON seçilmişse JOLT tanımı parse edilip istek gövdesi yeni JSON şemasına map edilir. JSON2XML seçilmişse ilgili bayraklar uygulanarak JSON içeriği XML’e çevrilir.
4. Karar Verme:
   • Eşleşme Var: Dönüştürülen gövde request pipeline’ına geri yazılır, hedef Endpoint’e güncel içerik gönderilir ve log kaydına dönüşüm tipi işlenir.
   • Eşleşme Yok: İstek orijinal yüküyle API Proxy (API Vekil Sunucusu) tarafından yönlendirilir; politika sayaçları güncellenmez.
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

• JSON2JSON Dönüşüm Motoru: JOLT spesifikasyonu ile alan yeniden adlandırma, hiyerarşi değiştirme ve veri zenginleştirme işlemlerini gerçekleştirir.
• JSON2XML Konfigürasyonu: Legacy sistemlere entegrasyon için JSON içeriklerini XML’e çevirirken null/boş alan yönetimi ve element paketleme seçenekleri sunar.
• Dönüşüm Test Laboratuvarı: Test Transformation Data modülü üzerinden JOLT şablonlarını canlı veriyle doğrulayıp çıktı farklarını inceleme imkânı verir.
• 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

• Global Politika Yayılım Kontrolü: Global politikalar güncellenirken kullanımda olan API Proxy ve Proxy Group listeleri otomatik kontrol edilip onay sürecine yönlendirir.
• Otomatik İsim Benzersizliği: Politika isimlerinin proje bazında çakışmaması için gerçek zamanlı doğrulama ve kullanıcıya görsel geri bildirim sağlar.
• Politika Akışı Entegrasyonu: Policy Flow modunda seçili politikayı diğer politikalarla zincirleyerek yeniden kullanım senaryolarına olanak tanır.
• Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Geliştirme, Test, Canlı Ortam) 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ç
Mikroservis Şema Uyumluluğu	Yeni versiyon Api Gateway’e gelen JSON alan isimleri farklı	transformationType=JSON2JSON, JOLT ile alan yeniden adlandırma	İstek gövdesi hedef şemaya uyar, backend kodu değiştirilmez.
Legacy XML Servisine Geçiş	Arka uç sadece XML kabul ediyor	transformationType=JSON2XML, unwrapElement=false, ignoreEmpty=true	JSON payload XML’e çevrilir, SOAP benzeri Endpoint sorunsuz cevaplar.
Çoklu Tenant Normalizasyonu	Tenant bazlı ekstra alanlar geliyor	JSON2JSON, joltValue ile gereksiz alanları kaldırma	Tenant farklarından bağımsız tekil JSON yapısı elde edilir.
Opsiyonel Alan Temizliği	Boş/null alanlar backend doğrulamasını bozuyor	JSON2XML, ignoreNull=true, ignoreEmpty=true	XML çıktısında gereksiz boş elemanlar oluşmaz, doğrulama geçer.
Gerçek Zamanlı Veri Zenginleştirme	Ek alan türetilmesi gerekiyor	JSON2JSON, JOLT’de defaultValue fonksiyonları	Çıktıya türetilmiş alan eklenir, servis tarafında hesaplama yapılmaz.
Dış Servis Entegrasyon Testi	JOLT değişiklikleri yayına alınmadan test edilmeli	JSON2JSON, test modülüyle örnek veri çalıştırma	Dönüşüm önceden doğrulanır, canlıda hata riski azalır.
Bölgesel Format Uyarlaması (opsiyonel)	Farklı bölgelerde tarih formatı bekleniyor	JSON2JSON, koşul ile header=Region kontrolü, JOLT format dönüşümü	Bölge bazlı JSON çıktıları tutarlı üretilir.

​

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 Dönüştürme 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 Dönüştürme 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_JSONTransform - 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ş JSON alanlarını normalize eder.” - 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: Dönüşüm Tipini Seçme	transformationType alanından JSON2JSON veya JSON2XML seçin. JSON2JSON seçildiğinde JOLT editörü açılır, JSON2XML seçildiğinde dönüştürme seçenekleri görünür.
Adım 5: JOLT Spesifikasyonunu Tanımlama (Varsa)	JSON2JSON için code editor üzerinde JOLT JSON yapısını girin, Test Transformation Data penceresinden çıktı doğrulaması yapın. Şablon kaydedilmeden önce sözdizimi hatalarını giderin.
Adım 6: JSON to XML Parametreleri (Varsa)	JSON2XML seçildiğinde ignoreNull, ignoreEmpty, useNullForNil, unwrapElement seçeneklerini işaretleyin. Legacy Endpoint ihtiyacına göre element paketleme veya boş alan davranışını ayarlayın.
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": "[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 dönüşüm yapılandırması 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 Politikayı API’ye Bağlama bölümüne bakabilirsiniz.

​

İleri Düzey Özellikler

Özellik	Açıklama ve Adımlar
JOLT Şablon Yönetimi	- Yeni JOLT tanımlarını JSON editörde versiyonlayın. - Test Transformation Data ekranında örnek veri çalıştırın. - Hata aldığınızda joltValue alanını düzenleyip tekrar deneyin.
Global Politika Güncelleme Onayı	- Kaydetmeden önce kullanımda olan API Proxy listesini görüntüleyin. - Gerekirse removeCurrentProxy ile etkilenmeyecek Proxy’leri geçici dışlayın. - Onay sonrası otomatik broadcast ile bağlı ekranlar güncellenir.
Policy Flow Seçimi	- Policy Flow modunda setPolicyFlowMode(true) ile çalışma modunu açın. - selectEvent sayesinde başka politikalarla zincir oluşturun. - Flow tamamlandığında INSERT_UPDATE_POLICY eventiyle orkestrasyonu kaydedin.

​

Best Practices

​

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Şema Eşleştirme	Kötü: JOLT şablonunu production verisi üzerinde denemeden yayınlamak. İyi: Test dataset ile manuel kontrol yapmak. En İyi: CI pipeline’da otomatik JOLT doğrulama çalıştırmak.
XML Entegrasyonu	Kötü: Tüm seçenekleri varsayılan bırakıp XML çıktısını incelememek. İyi: ignoreNull/ignoreEmpty parametrelerini gereksinime göre ayarlamak. En İyi: XSD şemasına karşı XML validasyonu yaparak sonuçları doğrulamak.
Koşul Yönetimi	Kötü: Politikanın her istekte çalışmasına izin vermek. İyi: Query Builder’da ortam veya header bazlı temel koşullar tanımlamak. En İyi: Çoklu kriterli koşullar kurarak gereksiz dönüşümleri azaltmak.
Hata Mesajları	Kötü: Varsayılan hata kodunu değiştirmeden bırakmak. İyi: JOLT hataları için spesifik mesaj ve kod tanımlamak. En İyi: Hata mesajında izleme ID’si ve destek yönlendirmesi sağlamak.
Versiyonlama	Kötü: Eski JOLT tanımlarını silmek. İyi: Export ile yedek alıp saklamak. En İyi: Kaynak kontrolünde branch bazlı JOLT sürümleri tutmak.

​

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Payload Doğrulama	JOLT ile gelen veride beklenmeyen alanların kaldırılamaması halinde zararlı içerik hedef servise ulaşabilir. Koşulları ve şema kontrollerini etkin tutun.
Hata Mesajı Hijyeni	Özelleştirilmiş hata mesajlarında iç sistem detaylarını paylaşmayın; yalnızca hata kodu ve genel açıklama verin.
Global Politika Yayılımı	Global politikalar güncellendiğinde kullanılan API Proxy listesini inceleyin, kritik servisler için değişiklik penceresi planlayın.
Audit Log İzleme	Dönüşüm politikalarını zorunlu olay olarak loglayın; beklenmeyen dönüşümleri erken tespit edin.
Yetkilendirme	Politika düzenleme yetkilerini minimum kullanıcıya verin; ROLE_DEPLOY_UNDEPLOY_PROXIES gerekli değilse kapatın.

​

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Geçersiz JOLT Dağıtımı	Neden kaçınılmalı: Sözdizimi hatalı JOLT, gateway’de 500 hatasına yol açar. Alternatif: Yayın öncesi Test Transformation Data ile doğrulayın.
Koşulsuz XML Dönüşümü	Neden kaçınılmalı: JSON2XML’in tüm isteklere uygulanması istemci beklentilerini bozar. Alternatif: Header/path koşulu tanımlayarak sadece gerekli çağrılarda kullanın.
İsim Çakışması	Neden kaçınılmalı: Aynı isimli politika import/export sırasında üzerine yazılabilir. Alternatif: Benzersiz prefix kullanın, isim doğrulama uyarılarını dikkate alın.
Global Güncelleme Onaysızlığı	Neden kaçınılmalı: Global politikayı kullanımda iken güncellemek tüm API Proxy trafiğini etkiler. Alternatif: Önce local kopya üzerinde test edip ardından onaylı dağıtım yapın.

​

Performans İpuçları

Kriter	Öneri / Etki
JOLT Karmaşıklığı	Öneri: Şablonu küçük parçalara bölün, nested operatörleri minimize edin. Etki: Dönüşüm süresi kısalır, CPU tüketimi düşer.
Koşul Ön Eleme	Öneri: Query Builder’da spesifik header/path filtreleri kullanın. Etki: Gereksiz dönüşüm çalıştırmaları engellenir.
XML Çıktı Boyutu	Öneri: ignoreEmpty ve ignoreNull seçeneklerini aktif kullanın. Etki: Daha küçük XML çıktı, ağ gecikmesi azalır.
Önbellek Kullanımı	Öneri: Sık kullanılan JOLT şablonlarını politika içindeki joltValue’da saklayın, runtime’da yeniden oluşturmayın. Etki: Serialization maliyetleri düşer.
Monitoring	Öneri: Politikaya özel metrikler (başarı/başarısız) için Gateway izleme panellerini yapılandırın. Etki: Performans sorunları hızlı tespit edilir.

​

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	JSON Dönüştürme Politikası hangi aşamada çalışır?	API Gateway içinde request pipeline’da, routing gerçekleşmeden önce çalışır ve güncel gövde hedef Endpoint’e iletilir.
Genel	Aynı anda kaç politika uygulanabilir?	Policy Group üzerinden birden fazla politika zincirlenebilir; her biri sırayla gövdeyi işleyecek şekilde yürütülür.
Teknik	JOLT şablonu hatalıysa ne olur?	Sistem hata mesajı sekmesinde tanımlı HTTP kodu ve mesajı döndürür; request backend’e ulaşmaz.
Teknik	JSON2XML dönüşümünde namespace yönetimi yapılabilir mi?	Mevcut bileşen temel JSON→XML dönüşümü sağlar; namespace ihtiyacı varsa JOLT ile ön hazırlık yapılmalıdır.
Kullanım	Politika local kopyaya nasıl alınır?	Detay sayfasındaki Localize butonu ile global politika local kopyaya çevrilir ve sadece seçili API’de kullanılır.
Kullanım	Değişiklikleri nasıl test edebilirim?	Test Transformation Data bileşeninde örnek JSON yükleyip yeni şablonun çıktısını canlı ön izleme ile karşılaştırabilirsiniz.