The WSO2 Enterprise Service Bus allows you to connect systems that normally would not be able to communicate. This inability comes for instance from a perspective that the systems do not speak each other’s language. An example: system A has a client number consisting of 6 digits where system B has 8 digits. Or of course any permutation of this or a host of other issues that hinder communication. In this WSO2 Tutorial we will show you how to create a REST to SOAP in WSO2 ESB and WSO2 API manager
Using the building blocks of the ESB, the mediators, we can take a message from system A and transform the message so system B can understand it. We might expand the client number to 8 digits or do a lookup in a table and find the corresponding client number for system B. But that is a situation where the language is the same, but the dialect is different.
There are also situations where the language is completely different, for instance an API call to a SOAP service. For those of you less familiar with this: with API (Application Programming Interface) I mean HTTP verb based calls like GET, PUT, POST and DELETE. In many cases API’s use JSON (Javascript Object Notation) to pass parameters to the service you are calling. An example: to access a banking service to retrieve an account balance you could use something like this:
http://acmebank.com:8243/mybank/v1.0.0/accounts/1111
The 1111 is the dummy account number we use. Of course in the real world this call would be secured so that not everyone has access. But the principle is clear, using a URL we retrieve the information for the account balance.
SOAP (Simple Object Access Protocol) is a different standard that uses XML (eXtensible Markup Language) and a rigid structure of SOAP Envelope, SOAP header and SOAP Body to send messages to backend services. Although SOAP still has merit it is becoming a less popular protocol due to its relatively high overhead, verbosity and rigidness, still there are a number of systems that use SOAP for very valid reasons though. A typical soap call would be:
http://acmebank.com:9766/HiRollerBankWS/services/accounts
With a payload of:
<soapenv:Envelope xmlns_soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns_hir="http://hirollerbankws.training.wso2.com/"> <soapenv:Header/>
<soapenv:Body>
<hir:checkBalance>
<!–Optional:–>
<accountNo>1111</accountNo>
</hir:checkBalance>
</soapenv:Body>
</soapenv:Envelope>
As you can see, the two ways of retrieving information are quite different. How do we make these two compatible?
ESB and API Manager
In this WSO2TORIAL we mention ESB and API Manager from WSO2. Why? Because these two products are linked to each other in the sense that they utilize the same components like Synapse and AXIS2 for mediation and transformation.
Apart from the fact that they are linked, they are also complementary. The API Manager excels in management, monitoting and monetization of APIS whereas the ESB is better at mediation and transformation, especially in more complex situations. The API Manager often fronts an ESB, each taking care of what the product is good at. So where I say ESB you can read API Manager as well. The API Gateway is a mini ESB that allows mediation to be done when the API call flows through it.
So when it says ESB it also applies to the API Manager.
AXIOM
The Axis Object Model (AXIOM) is the internal AXIS2 model that is used for mediation and transformation and it is SOAP based. In other words, any message that enters the ESB is transformed into a soap Message whatever format it came in with. When the message goes to the backend service it gets transformed into whatever format it needs to be in.
So a REST API call to a REST backend will become a SOAP message in the ESB and will be transformed to REST when it leaves the ESB. So technically transforming messages is possible!
In the image above the message builder for that specific incoming message (e.g. REST) is invoked to transform the message to AXOIM and with the outgoing message the same happens in the message formatter to transform into the required format that goes to the backend.
There are a number of message formatters and message builders included with the ESB (these can be turned on in axis2.xml (in the /repository/conf/axis2 directory). If you need a message builder or formatter outside of the currently included ones, you can create your own custom message builder or message formatter. See https://docs.wso2.com/display/ESB500/Writing+a+Custom+Message+Builder+and+Formatter
Determining the message formatter
So how does the ESB determine the message formatter it needs to use?
It is determined in part by the endpoint definition where we have the possibility to not only define the address of the endpoint but also the format. Below you find part of the XML configuration for an address-endpoint.
<address uri="endpoint address" [format="soap11|soap12|pox|rest|get"] [optimize="mtom|swa"] [encoding="charset encoding"] [statistics="enable|disable"] [trace="enable|disable"]>
As you can see there is a possibility to define it as SOAP (v1.1 or v1.2), POX (Plain Old Xml), REST (HTTP endpoint) or get (transforming it in a HTTP GET).
Mind you, this is for an address endpoint. There is also an HTTP endpoint that has its own syntax.
There is also the setting of the messageType which we need to set to “text/xml” in this case where we have a soap 1.1 endpoint.
An example using the API Manager
So let’s imagine that we create a REST api that takes an account number and makes a SOAP message to send to the SOAP endpoint. This is a quite simple transformation that can easily be done from the API Manager
We will use the API Manager 2.0.0 for this. We start by defining a context, version and URL pattern.
mybank is the context, v1.0.0 is the version and /accounts/1111 is the URL pattern. The latter of course being an actual example, the real pattern is /accounts/{AccountID}.
In this pattern the {AccountID} is the variable that we will refer to as uri.var.AccountID
The above screenshot is showing the API Creation wizard which you can use in the WSO2 API Publisher. It shows the first step after starting the wizard.
When defining the implementation we need to add a SOAP endpoint with a SOAP v1.1. format (under advanced endpoint definition). You can open this advanced configuration by clicking the cog-wheel in next to the Production- or Sandbox endpoint input fields in the “Implement” step of the API-creation wizard.
The endpoint will point to the WSO2 Application server where the HiRollerBank app (which has our acountbalance retrieval function) is running.
The Production endpoint is pointing to a local address as the App server is running in a local environment in this example.
In the Message Mediation Policies section we have uploaded two sequences: REST2SOAP and SOAP2REST that will do the transformation from REST to SOAP back and forth.
REST2SOAP makes sure that we create a correct SOAP body and will set the messageType to text/xml (=SOAP v1.1).
The SOAP2REST will transform the message to application/json putting the JSON response back to the client.
So we are nearly there but still need to fill in the final tab.
These settings are mostly arbitrarily chosen, you have freedom to make your own choices here.
Now we need to Save and Publish the API to finish the wizard.
Testing it
But does it work? That is a good question. Let’s go in to the API store and subscribe to the API. We will not go into detail to describe the whole process of Sign-Up and Subscription. It is largely self-explanatory process and alternatively you can attend a training here @Yenlo where you can learn how to work with the WSO2 API Manager.
When we have subscribed to the API, generated the token, we can use the API Console to test it out. Please note that the token is different for each user and needs refresh when it is expired.
Click on the GET and fill in 1111.
You can see the response coming back in the form of a JSON message with a balance of 1234,5.
So now we have a simple REST frontend to a SOAP Backend.
If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
Yenlo is the leading, global, multi-technology integration specialist in the field of API-management, Integration technology and Identity Management. Known for our strong focus on best-of-breed hybrid and cloud-based iPaaS technologies.
Yenlo is the product leader and multi-award winner in WSO2, Boomi, MuleSoft and Microsoft Azure technologies and offers best-of-breed solutions from multiple leading integration vendors.
With over 240+ experts in the API, integration, and Identity Access Management domain and over $35 million in annual revenue, Yenlo is one of the largest and best API-first and Cloud-first integration specialists worldwide.
