SOAP Web Servisi REST API Olarak Sunma

SOAP protokolü ile geliştirilmiş bir Web Servisin REST olarak açılması talebi özellikle, var olan servislerin yeni geliştirilen mobil uygulamalar ya da JavaScript tabanlı Web uygulamaları tarafından kullanılması gibi durumlarda sıklıkla ortaya çıkmaktadır. Var olan servisin REST ile yeniden yazılması ya da metotlarını taklit eden yeni bir REST API geliştirilmesi seçenekleri zaman ve maliyet açısından etkin çözümler değildir.

Apinizer, SOAP Web servislerin REST olarak açılmasını ve bunun için gerekli bütün dönüşümlerin konfigürasyonla yapılabilmesini sağlar.

Bu bölümde, bir SOAP Web Servisin istemcilere nasıl REST olarak sunulabileceği anlatılmaktadır.

SOAP Web Servisten REST Tipinde API Proxy Oluşturma

1- Yeni API Proxy oluşturulurken WSDL tipi için URL Girme (Enter URL) ya da Dosya Yükle (Upload File) seçeneklerinden uygun olan seçilir. Bu örnekte URL Girme seçeneği kullanılmıştır.

2- URL girilip Parse tuşuna basıldıktan sonra gelen ekranda Protokol Dönüşümü (Protocol Transformation) bölümünde REST to SOAP to REST seçeneği işaretlenir. Diğer zorunlu bilgiler de doldurularak API Proxy oluşturulur.

Metot Dönüşüm Ayarları

API Proxy oluşturulduktan sonra, istenirse metotların istek ve yanıt mesajları için REST - SOAP mesaj yapıları arasında nasıl dönüşüm yapılacağı özelleştirilebilir. Bunun için API Proxy'nin Geliştirme (Development) sekmesine gidilir.

Sol taraftaki metot listesinde Hepsi (All) seçiliyken, orta bölümde üstte istek ve altta yanıt mesajlarının dönüşüm ayarlarını açan simgeler (görselde kırmızı ile işaretlenmiş simgeler) görünür.

Örneğin istek mesajlarına ait olan simgeye tıklandığında aşağıdaki protokol dönüşüm arayüzü açılır. Bu arayüzde İstek Mesajı Seçenekleri (Request Options) ve Yanıt Mesajı Seçenekleri (Response Options) sekmeleri bulunmaktadır. Kullanıcının hangi simgeye tıkladığına bağlı olarak ilgili sekme açılır.

Bu arayüzde REST protokolüne uygun olarak gelen istek mesajının Backend API'ye gönderilmeden önce SOAP yapısına uygun hale nasıl getirileceğine ilişkin biçimlendirmeler yapılır. Sol taraftan mesaj yapısı güncellenecek olan metot seçilir. Sağ tarafta ise o metoda ilişkin dönüşüm ayarları yapılır.

Dönüşüm Seçenekleri

Bir SOAP Servis istemcilere REST olarak açıldığı zaman istek ve yanıt mesajlarının dönüştürülmesi gerekir. İstemciden gelen JSON mesaj SOAP servise gönderilmeden önce XML mesajına, SOAP servisin döndürdüğü XML mesaj ise istemciye gönderilmeden önce JSON mesajına dönüştürülmelidir. Bu dönüşümün yapılabilmesi için çeşitli seçenekler bulunmaktadır:

Jackson Transformation: İstek ve yanıt mesajlarında kullanılacak olan JSON mesajının sade ve kolay anlaşılabilir olması gereken durumlarda tercih edilir. Diğerlerine göre oldukça özelleştirilebilir. En çok tercih edilen yöntemdir.
JsonML Transformation: İstek ve yanıt mesajlarında kullanılacak olan JSON mesajının XML Attribute değerlerini ve XML Namespace'lerini de içermesi isteniyorsa tercih edilir. Diğerlerine göre JSON formatı daha karışıktır. Gösterimindeki Namespace'lerden dolayı XML gösterime benzediğinden veri büyüklüğü artar.
Template Message: Gelen JSON mesajının hangi formatta olduğundan bağımsız, SOAP Servise gönderilecek olan XML şablonunu oluşturmak mantığı üzerine çalışır. XML şablonundaki parametrelerin doldurulması için "istek/yanıt verisi düzenlemesi (request/response data manipulation)" kullanılır. Çoklu alt eleman desteği olmadığından, basit yapıdaki XML'lerin olduğu durumda kullanışlıdır. Özellikle JSON mesajı yerine istek başlığı (request header) veya parametresinden (request parameter) veri alınıp çalışılmak isteniyorsa tercih edilir.

Aşağıda her bir seçenek için var olan alanların ne anlama geldiği açıklanmaktadır.

İstek Mesajları Dönüşüm Seçenekleri

Bu bölümde istek mesajlarının dönüşüm seçeneklerinin detayları anlatılmaktadır.

Jackson Dönüşümü Kullan (Use Jackson Transformation)

Alan	Açıklama
NULL değerleri görmezden gel (Ignore fields with NULL)	İşaretlenirse, Backend API'ye gönderilecek XML mesajın içine, istekte gelen JSON mesajdaki NULL değerleri XML Element olarak eklenmez.
Boş değerleri görmezden gel (Ignore EMPTY fields)	İşaretlenirse, Backend API'ye gönderilecek XML mesajın içine, istekte gelen JSON mesajdaki boş değerler XML Element olarak eklenmez.
NULL değerler için xsi:nil="true" kullan (Use xsi:nil="true" for NULL values)	İşaretlenirse, Backend API'ye gönderilecek XML mesajın içine, istekte gelen JSON mesajdaki NULL değerleri için xsi:nil="true" niteliği kullanılır. Aksi taktirde XML mesajın içine ilgili değer için boş eleman eklenir. Değerinin aktifleştirilmesi, json mesajında null olarak gönderilen değerin xml’e dönüştürülürken xsi:nil="true" alanı eklenerek iletilmesini sağlar.
Hedef XPath (Target XPath)	Gelen JSON mesajı XML'e dönüştürüldükten sonra elde edilen XML'in, SOAP servisin beklediği XML mesajın içinde nereye koyulacağını belirtir.
Alt Elemanları Değiştir (Replace Children)	Seçenek işaretlenirse, Target XPath'in çıktı öğesinin alt öğeleri silinerek JSON'dan dönüştürülen kısım bunların yerine eklenir. Aksi takdirde eleman tamamen değiştirilir.
Dizi olan elemanlar (Paths for Arrays within message)	JSON mesajın içinde hangi bölümlerin array olarak yorumlanması gerektiğini belirtir. Her bir Path, Hedef XPath'in seviyesinden (Hedef XPath verilmemişse en üst seviyeden) başlayarak ve seviyeler arasına # işareti koyularak yazılır. Örnek: "envelope#body#abc" ifadesi, "envelope" içindeki, "body"'nin içindeki "abc" elemanının array olarak işleme alınacağını belirtir. Array içinde array olması durumunda en içteki Array'in pathinden başlanarak yazılır. Örneğin abc elementi array ve içinde def elementi array olarak yer alıyorsa "envelope#body#abc#def, envelope#body#abc" sırasıyla yazılmalıdır.
İstek Verisi Düzenlemesi (Request Data Manipulation)	Orijinal isteğin herhangi bir bölümü dönüştürülmüş isteğin belirtilen bir bölümüne aktarılabilir. Kaynak Değer/Değişken, orijinal istek mesajının hangi bölümünün aktarılacağını, Hedef Değer/Değişken ise Kaynak Değer/Değişken ile belirtilen bölümün dönüştürülmüş mesaj içinde nereye koyulacağını belirtir.
Örnek Mesaj Göster (Show Sample Message)	Ayarlara göre oluşan İstek Mesajı görüntülenebilir.

Dönüştürülmüş Mesaj Örneği:

API Proxy'nin İstemciden Beklediği JSON İstek Mesajı

Backend API/Servisin beklediği XML İstek Mesajı

{
    "Add": {
        "intB": "?",
        "intA": "?"
    }
}

YML

<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:Add>
         <tem:intA>?</tem:intA>
         <tem:intB>?</tem:intB>
      </tem:Add>
   </soap:Body>
</soap:Envelope>

XML

JsonML Dönüşümü Kullan (Use JsonML Transformation)

Alan	Açıklama
JSON Nesnesi kullan (Use JSON Object)	XML Elemanlarını JSON Nesneleri (JSON Objects) olarak dönüştürür.
JSON Dizisi kullan (Use JSON Array)	XML Elemanlarını JSON Dizisi (JSON Array) olarak dönüştürür.
İstek Verisi Düzenlemesi (Request Data Manipulation)	Orijinal isteğin herhangi bir bölümü dönüştürülmüş isteğin belirtilen bir bölümüne aktarılabilir. Kaynak Değer/Değişken, orijinal istek mesajının hangi bölümünün aktarılacağını, Hedef Değer/Değişken ise Kaynak Değer/Değişken ile belirtilen bölümün dönüştürülmüş mesaj içinde nereye koyulacağını belirtir.
Örnek Mesaj Göster (Show Sample Message)	Ayarlara göre oluşan İstek Mesajı görüntülenebilir.

Dönüştürülmüş Mesaj Örneği:

Dönüşüm Tipi

API Proxy'nin İstemciden Beklediği JSON İstek Mesajı

Backend API/Servisin beklediği XML İstek Mesajı

JSON Object

{
    "soap:Envelope": {
        "xmlns:tem": "http://tempuri.org/",
        "soap:Header": "",
        "xmlns:soap": "http://www.w3.org/2003/05/soap-envelope",
        "soap:Body": {
            "tem:Add": {
                "tem:intA": "?",
                "tem:intB": "?"
            }
        }
    }
}

YML

<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:Add>
         <tem:intA>?</tem:intA>
         <tem:intB>?</tem:intB>
      </tem:Add>
   </soap:Body>
</soap:Envelope>

XML

JSON Array

[
    "soap:Envelope",
    {
        "xmlns:tem": "http://tempuri.org/",
        "xmlns:soap": "http://www.w3.org/2003/05/soap-envelope"
    },
    [
        "soap:Header"
    ],
    [
        "soap:Body",
        [
            "tem:Add",
            [
                "tem:intA",
                "?"
            ],
            [
                "tem:intB",
                "?"
            ]
        ]
    ]
]

YML

<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:Add>
         <tem:intA>?</tem:intA>
         <tem:intB>?</tem:intB>
      </tem:Add>
   </soap:Body>
</soap:Envelope>

XML

Şablon Mesajını Kullan (Use Template Message)

Alan

Açıklama

Şablon Message

(Template Message)

Backend API/Servisin beklediği XML istek mesajı şablonu

İstek Veri Düzenlemesi

(Request Data Manipulation)

Orijinal isteğin herhangi bir bölümü dönüştürülmüş isteğin belirtilen bir bölümüne aktarılabilir. Kaynak Değer/Değişken, orijinal istek mesajının hangi bölümünün aktarılacağını, Hedef Değer/Değişken ise Kaynak Değer/Değişken ile belirtilen bölümün dönüştürülmüş mesaj içinde nereye koyulacağını belirtir.

Yanıt Mesajları Dönüşüm Seçenekleri

Bu bölümde yanıt mesajlarının dönüşüm seçeneklerinin detayları anlatılmaktadır.

Jackson Dönüşümü Kullan (Use Jackson Transformation)

Alan	Açıklama
NULL değerleri görmezden gel (Ignore fields with NULL)	Seçili ise, Backend API'den gelen XML mesajdaki, NULL alanlar JSON mesaja eklenmez.
Boş değerleri görmezden gel (Ignore EMPTY fields)	Seçili ise, Backend API'den gelen XML mesajdaki, NULL alanlar JSON mesaja boş değer olarak eklenmez.
Numerik değerleri String olarak yaz (Write Numbers as Strings)	Seçili ise numerik değerler JSON mesaja string olarak yazılır.
NULL değerler için xsi:nil="true" kullan (Use xsi:nil="true" for NULL values)	XML mesajda xsi:nil="true" niteliği ile gelen verilerin json’a dönüştürülürken null olarak iletilmesini sağlar.
Kaynak XPath (Source XPath)	XML olarak dönen yanıt mesajının JSON'a dönüştürülecek olan kısmının XPath’ini girilir.
Elemanı Çöz (Unwrap Element)	İşaretlenirse, Kaynak XPath ile verilen elemanın içini (çocuklarını), işaretlenmezse elemanın kendisini (içindekilerle/çocuklarıyla beraber) dönüştürür.
Dizi olan elemanlar (Paths for Arrays within message)	JSON mesajın içinde hangi bölümlerin Array olarak yorumlanması gerektiğini belirtir. Her bir Path, Kaynak XPath'in seviyesinden (Kaynak XPath verilmemişse en üst seviyeden) başlayarak ve seviyeler arasına # işareti koyularak yazılır. Örnek: envelope#body#abc ifadesi, envelope içindeki, body'nin içindeki abc elementinin array olarak işleme alınacağını belirtir. Array içinde array olması durumunda en içteki Array'in pathinden başlanarak yazılır. Örneğin abc elementi array ve içinde def elementi array olarak yer alıyorsa "envelope#body#abc#def, envelope#body#abc" sırasıyla yazılmalıdır.
Başarı Durumunda Yanıt Verisi Düzenlemesi (Response Data Manipulation on Success)	Orijinal yanıtın herhangi bir bölümü dönüştürülmüş yanıtın belirtilen bir bölümüne aktarılabilir. Kaynak Değer/Değişken, orijinal yanıt mesajının hangi bölümünün aktarılacağını, Hedef Değer/Değişken ise Kaynak Değer/Değişken ile belirtilen bölümün dönüştürülmüş mesaj içinde nereye koyulacağını belirtir. Tanımlanan işlemler yalnızca Backend API/Servisin başarılı yanıt döndürmesi durumunda gerçekleştirilir.
Örnek Mesaj Göster (Show Sample Message)	Ayarlara göre oluşan Yanıt Mesajı görüntülenebilir.

Dönüştürülmüş Mesaj Örneği:

Backend API/Servisin döndürdüğü XML Yanıt Mesajı

API Proxy'nin İstemciye Döndürdüğü JSON Yanıt Mesajı

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body>
		<AddResponse xmlns="http://tempuri.org/">
			<AddResult>?</AddResult>
		</AddResponse>
	</soap:Body>
</soap:Envelope>

XML

{
  "AddResponse" : {
    "AddResult" : "?"
  }
}

YML

JsonML Dönüşümü kullan (Use JsonML Transformation)

Alan	Açıklama
JSON Nesnesi kullan (Use JSON Object)	XML Elemanlarını JSON Nesneleri (JSON Objects) olarak dönüştürür.
JSON Dizisi kullan (Use JSON Array)	XML Elemanlarını JSON Dizisi (JSON Array) olarak dönüştürür.
Başarı Durumunda Yanıt Verisi Düzenlemesi (Response Data Manipulation on Success)	Orijinal yanıtın herhangi bir bölümü dönüştürülmüş yanıtın belirtilen bir bölümüne aktarılabilir. Kaynak Değer/Değişken, orijinal yanıt mesajının hangi bölümünün aktarılacağını, Hedef Değer/Değişken ise Kaynak Değer/Değişken ile belirtilen bölümün dönüştürülmüş mesaj içinde nereye koyulacağını belirtir. Tanımlanan işlemler yalnızca Backend API/Servisin başarılı yanıt döndürmesi durumunda gerçekleştirilir.
Örnek Mesaj Göster (Show Sample Message)	Ayarlara göre oluşan Yanıt Mesajı görüntülenebilir.

Dönüştürülmüş Mesaj Örneği:

Dönüşüm Tipi

Backend API/Servisin döndürdüğü XML Yanıt Mesajı

API Proxy'nin İstemciye Döndürdüğü JSON Yanıt Mesajı

JSON Object

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body>
		<AddResponse xmlns="http://tempuri.org/">
			<AddResult>?</AddResult>
		</AddResponse>
	</soap:Body>
</soap:Envelope>

XML

{
  "soap:Envelope" : {
    "xmlns:xsd" : "http://www.w3.org/2001/XMLSchema",
    "xmlns:soap" : "http://www.w3.org/2003/05/soap-envelope",
    "xmlns:xsi" : "http://www.w3.org/2001/XMLSchema-instance",
    "soap:Body" : {
      "AddResponse" : {
        "xmlns" : "http://tempuri.org/",
        "AddResult" : "?"
      }
    }
  }
}

YML

JSON Array

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body>
		<AddResponse xmlns="http://tempuri.org/">
			<AddResult>?</AddResult>
		</AddResponse>
	</soap:Body>
</soap:Envelope>

XML

[
	"soap:Envelope",
	{
		"xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
		"xmlns:soap": "http://www.w3.org/2003/05/soap-envelope",
		"xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance"
	},
	[
		"soap:Body",
		[
			"AddResponse",
			{
				"xmlns": "http://tempuri.org/"
			},
			[
				"AddResult",
				"3"
			]
		]
	]
]

YML

Şablon Mesajını Kullan (Use Template Message)

Alan

Açıklama

Şablon Message

(Template Message)

İstemciye döndürülecek JSON yanıt mesajı

Başarı Durumunda Yanıt Verisi Düzenlemesi

(Response Data Manipulation on Success)

Orijinal yanıtın herhangi bir bölümü dönüştürülmüş yanıtın belirtilen bir bölümüne aktarılabilir. Kaynak Değer/Değişken, orijinal yanıt mesajının hangi bölümünün aktarılacağını, Hedef Değer/Değişken ise Kaynak Değer/Değişken ile belirtilen bölümün dönüştürülmüş mesaj içinde nereye koyulacağını belirtir. Tanımlanan işlemler yalnızca Backend API/Servisin başarılı yanıt döndürmesi durumunda gerçekleştirilir.