From REST to SOAP in WSO2 ESB and WSO2 API Manager

Posted by Rob Blaauboer on 15 Jun, 2017

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!

REST to SOAP in WSO2 ESB and WSO2 API Manager-Message builder

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.

 http://acmebank.com:8243/mybank/v1.0.0/accounts/1111

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

REST to SOAP in WSO2 ESB and WSO2 API Manager-AOI Creation Wizard

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.

REST to SOAP in WSO2 ESB and WSO2 API Manager-Advanced Endpoint Configuration

The endpoint will point to the WSO2 Application server where the HiRollerBank app (which has our acountbalance retrieval function) is running.

REST to SOAP in WSO2 ESB and WSO2 API Manager-Production endpoint

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). 

REST to SOAP in WSO2 ESB and WSO2 API Manager - Rest2soap

The SOAP2REST will transform the message to application/json putting the JSON response back to the client.

REST to SOAP in WSO2 ESB and WSO2 API Manager-Soap2Rest

So we are nearly there but still need to fill in the final tab.

REST to SOAP in WSO2 ESB and WSO2 API Manager-Configurations Rest to Soap

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.

REST to SOAP in WSO2 ESB and WSO2 API Manager-HiRollerBank-v1.0.0

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.

REST to SOAP in WSO2 ESB and WSO2 API Manager-HiRollerBank-v.1.0.0

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.

REST to SOAP in WSO2 ESB and WSO2 API Manager-AccountID-ResttoSOAP

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 Tutorialswebinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs. 

ESB Selection Guide White Paper 

Topics: WSO2 ESB, WSO2 API, REST, SOAP

Written by Rob Blaauboer

Rob Blaauboer
Rob is a Senior Business Consultant and Solution Architect with more than twenty years experience. In addition to his work he is an active blogger working on a number of articles on the ‘Internet of Things’ and a WSO2 ‘Getting Started with …’ series (WSO2 tutorial) in which he talks about WSO2 components and their purpose especially aimed at non technical readers. Rob is a WSO2 expert and official WSO2 trainer.