This is about work I did on an online payment front end for a utility company. It’s about using a REST API as a facade in front of a legacy SOAP API.

SOAP is complicated, intricate and over engineered. Although it is probably not used for many new interfaces, there are plenty of legacy APIs that still need to be accessed by new applications.

The good news is that using an existing SOAP API is much much easier than providing a new one.

An aside, how did SOAP get to be so complicated ? Partly its down to the choice of XML to carry the data. From that you get name spaces, schema versions and abstractions for types, operations and bindings. I think the underlying reason is because the people who wrote the specifications had maths brains rather than engineering minds. Something as simple as passing three parameters to a function can require hundreds of lines of terse descriptions in a Web Service Definition file.

Pretend to be a SOAP

Although the SOAP server is very very fussy about the xml it receives, it does not actually care much about where that comes from. If you can find an example SOAP message, you can insert your own parameter values into boiler plate XML text, POST it off and wait for the return.

The gigantic SAP / J2EE system on the other side will never know that you don’t own an equally impressive enterprise set up.

Using Postman to experiment with the SOAP API

Before writing a node server to make the HTTP POST to the SOAP API, it’s a good idea to try it out with Postman first. You can see the return values and write Postman tests to show that the API does what you expect.

The API used here is defined in this WSDL. The call used here is called CountryCurrency. It expects a country code and returns the currency for that country.

The example end point is at

http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso

and the HTTP Content-Type is “text/xml; charset=utf-8”

The XML to POST is shown below. The only part that semantically matters to the overall system is the country code ‘US’, all the other XML is a means to an end.

Postman lets you run some Javascript to test the response and its a handy way to parse the result. The screenshot below shows a test.

Postman tests are a convenient way to experiment with parsing the verbose XML from a SOAP response.

So by using Postman its possible to try out boiler plate XML to make a SOAP request, and find out where to insert the values, in this case it was the country code “US”.

A node server to translate REST to SOAP

Once you know how to insert your values into the boiler plate XML, call the end point and parse the result, the hard part is done.

The node server just listens for incoming REST calls and synchronously forwards them on to the SOAP API. It then parses the result as shown in the test above, and returns the result.

Security tokens on the node and SOAP APIs check for authorisation.

In the case of the work I did, the SOAP message just needed a customer id, an amount of money and a callback id.

REST and SOAP are not really directly comparable, in that REST does not define parameter types, or even their presence. Code to validate params has to be added on after they arrive. In a way SOAP WDSL files are analogous to statically typed languages where everything is pinned down at compile time. REST is more like an untyped protocol that requires an extra layer of rigour to make sure calls are well formed.

But thats where Swagger, OpenAPI Specification and protocols like JSON API RESOURCES shine.