JSON is a lightweight data exchange format used in many web applications.
WSO2 ESB supports sending and receiving JSON messages out-of-the-box. Exposing a SOAP web service over JSON is explained under
sample 440 in WSO2 ESB official documentation. This post is to summarize steps of invoking a pass-through proxy service which accepts JSON request, forwards it to a RESTful service and reply back with JSON response (JSON-in, JSON-out).
Pre-requisite:
- Download and extract the binary distribution of WSO2 ESB-4.5.1
- I will use WSO2 Application Server-5.0.1 to deploy RESTful backend web service. You can use any server as the backend. However, in order to follow the steps mentioned in this post, you should use WSO2 Application server.
Step 1:
First, we need to setup the backend web service. We will deploy a
JAX-RS based restful service which consumes and produces JSON messages. You can download this RESTful web service(jaxrs_basic.war) from
here.
Step 2:
Start WSO2 Application Server, log in to management console and navigate to
Manage --> Applications --> List.
You will notice the web applications which are deployed by default in WSO2 Application Server. Since we already have a JAX-RS web app with the name jaxrs_basic, delete the default jaxrs_basic web application.
Now, we can deploy our jaxrs_basic web application (Note that, jaxrs_basic is a modified version of default sample jax-rs web application which has been customized to consume and produce JSON messages).
Go to
Manage --> Applications -->Add --> JAX-WS/JAX-RS.
Upload JAX-WS/JAX-RS Applications page will be shown. Browse the downloaded jaxrs_basic.war and click on upload. New JAX-RS web service will be deployed in WSO2 Application Server.
Step 3:
The auto-generated WADL of the RESTful web service can be obtained by accessing http://<wso2_application_server_hostname>
:<wso2_application_server_port>/jaxrs_basic/services/customers?_wadl
From there, you will identify the POST URL of 'customer' resource;
http://<wso2_application_server_hostname>:<wso2_application_server_port>/jaxrs_basic/services/customers/customerservice/customers
We will forward a message to the above URL from WSO2 ESB.
Step 4:
Now we have the backend web service, ready to process messages. Let's create a pass-through proxy service in ESB. Obviously, the endpoint URL will be the one mentioned above.
<proxy xmlns="http://ws.apache.org/ns/synapse" name="jsonproxy" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
<target>
<outSequence>
<send/>
</outSequence>
<endpoint>
<address uri="http://localhost:9764/jaxrs_basic/services/customers/customerservice/customers"/>
</endpoint>
</target>
<description></description>
</proxy>
Either using Pass Through Proxy template in WSO2 ESB management console or using file system, deploy the above proxy service.
Step 5:
Let's send a JSON request to our proxy service. I will use soapUI as usual since it is the best tool out there to invoke web services.
Open soapUI project and add a HTTP request test step to any existing test suite. Change the default method as POST. Enter the proxy service endpoint URL (http://<esb_host_name>:8280/services/jsonproxy) as the
Request URL.
Set the media type as application/json and add the following JSON request to POST body text area.
{
"Customer": { "name": "charitha" }
}
Finally, your soapUI request editor will look like the following.
Submit the request. You will get a JSON response back as shown below. WSO2 ESB will seamlessly forward JSON request to RESTful web service and forward the JSON response to soapUI.
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Server: WSO2 Carbon Server
Date: Sat, 12 Jan 2013 13:34:31 GMT
Transfer-Encoding: chunked
{"Customer":{"id":"125","name":"charitha"}}
NOTE:
In the previous versions of ESB (4.0.3 etc), you should add JSON message builders and formatters to ESB_HOME/repository/conf/axis2.xml in order to enable JSON message processing capabilities in ESB. (See
http://docs.wso2.org/wiki/display/ESB403/ESB+and+JSON)
However, these builder and formatters are enabled by default in WSO2 ESB version 4.5.1 and later. In addition to that, you may need to set the following property in IN and OUT paths of proxy services and sequences in previous ESB versions.
<property name="messageType" value="application/json" scope="axis2" />
