rest2Soap

Description

Converts REST requests into SOAP messages.

Can be used in

spring:beans, api, bean, if, interceptor, internalProxy, proxy, registration, request, response, serviceProxy, soapProxy, stompProxy, swaggerProxy, transport and wsStompReassembler

Syntax

				<rest2Soap>
					<mapping >*
				</rest2Soap>

Listing 1: rest2Soap Syntax

Sample

			<serviceProxy port="2000">
				<rest2Soap>
					<mapping regex="/bank/.*" soapAction=""
						soapURI="/axis2/services/BLZService" requestXSLT="blz-request.xsl"
						responseXSLT="blz-response.xsl" />
					<mapping regex="/shop/.*" soapAction=""
						soapURI="/axis2/services/ShopService" requestXSLT="shop-request.xsl"
						responseXSLT="shop-response.xsl" />
				</rest2Soap>		
			</serviceProxy>

Listing 2: rest2Soap Example

Child Elements

Position	Cardinality	Description	Element
1	0..*	Specifies the mappings. The first matching mapping will be applied to the request.	mapping

Example

This blog post describes a sample usage of rest2soap: It shows a complete translation of JSON REST requests (GET, POST, DELETE) into SOAP calls for a demo web service, as well as SOAP responses into HTTP status codes, messages and headers.

Also take a look at examples/rest2soap and examples/rest2soap-json within the Membrane ESB distribution.

Explanation

The rest2Soap interceptor acts on requests according to the first mapping whose regex matches the request's path.

Requests

Requests are first transformed into XML using a generic format to represent all request data (see below for an example).

Then, the XSLT transformation specified by requestXSLT is applied. The output of this transformation should be a valid SOAP request.

Then the destination URL of the request is set to the value of soapURI, and Membrane's request processing continues (probably forwarding the request to its destination).

Responses

The XSLT transformation specified by responseXSLT is applied.

If the output of the transformation is XML and the root element's namespace is "http://membrane-soa.org/schemas/http/v1/", the document is "unwrapped": HTTP status code and message, as well as headers are set on the response, and the <body> element's content is set as the message body. (see blog)

If the request contained a HTTP header Accept: application/json and the resposes's Content-Type header is still XML, the XML body is then transformed into JSON.

Debugging Details

To develop your custom setup, it is advised to set "log4j.logger.com.predic8=debug" in conf/log4j.properties: This way, you will see the steps your request takes in every detail in the log.

Example

We describe a sample request for the rest2soap example contained in the distribution.

The sample's configuration file has the following content:

				<serviceProxy port="2000">
					<rest2Soap>		
						<mapping regex="/bank/.*" soapAction=""
							soapURI="/axis2/services/BLZService" 
							requestXSLT="get2soap.xsl"
							responseXSLT="strip-env.xsl" />
					</rest2Soap>
					<target host="thomas-bayer.com" />
				</serviceProxy>

Listing 3: rest2Soap Configuration Example

Locally requesting the URL "http://localhost:2000/bank/37050198" causes the following GET request to be sent:

				GET /bank/37050198 HTTP/1.1
				User-Agent: curl/7.23.1 (x86_64-pc-win32) libcurl/7.23.1 OpenSSL/0.9.8r zlib/1.2.5
				Host: localhost:2000
				Accept: */*

Listing 4: REST to SOAP: HTTP GET sample request

This GET request is tranformed by Membrane's rest2soap interceptor into the following XML:

				<?xml version="1.0" ?>
				<http:request method="GET" http-version="1.1" xmlns:http="http://membrane-soa.org/schemas/http/v1/">
					<uri value="/bank/37050198">
						<path>
							<component>bank</component>
							<component>37050198</component>
						</path>
					</uri>
					<headers>
						<header name="User-Agent">curl/7.23.1 (x86_64-pc-win32) libcurl/7.23.1
							OpenSSL/0.9.8r zlib/1.2.5</header>
						<header name="Host">localhost:2000</header>
						<header name="Accept">*/*</header>
						<header name="X-Forwarded-For">127.0.0.1</header>
					</headers>
					<body type="plain"><![CDATA[]]>
					</body>
				</http:request>

Listing 5: REST to SOAP: HTTP GET sample request, transformed to XML

The rest2soap interceptor the applies the XSLT transformation get2soap.xslt (see examples/rest2soap/get2soap.xslt within the distribution). This results in:

				<?xml version="1.0" encoding="UTF-8"?>
				<s11:Envelope xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/">
					<s11:Body>
						<blz:getBank xmlns:blz="http://thomas-bayer.com/blz/">
							<blz:blz>37050198</blz:blz>
						</blz:getBank>
					</s11:Body>
				</s11:Envelope>

Listing 6: REST to SOAP: HTTP GET sample request, transformed to XML, XSLT applied

The request is then forwarded to the value of soapURI (or, with lower priority, the target host), which results in "http://thomas-bayer.com/axis2/services/BLZService" in our example.

Request Body Transformations

If the request body (which is empty in the example) is XML or JSON and the request's Content-Type header is set appropriately, the body will be embedded as a child of the <body>-element (instead of the CDATA-section above). Any JSON data is, of course, first transformed into an XML format.