In recent months I’ve had to work with Simple Object Access Protocol (SOAP) APIs and XML POST based APIs, both of which are a nightmare when compared to RESTful APIs. These protocols are mostly a nightmare when working in Node.js where the framework isn’t designed to handle WSDLs. I’ll get into definitions in a second, however in this blog post I wish to cover how I handle XML data in Node.js (creating and parsing) and how I handle interfacing with SOAP APIs.

Interfacing With XML

Interfacing with XML is a two way street; there is going to JSON from XML or going from XML to JSON. Node.js is much better at dealing with JSON than it is with XML (It is Javascript after all) and in my opinion JSON is easier to read and reason about. When parsing XML to JSON I like to use xml2js.

xml2js works very simply with a .parseString() method that handles XML sensibly in the conversion to JSON. Onto of this it is quick and stays out of your way. Here is an example of an XML payload translated to a JSON one:

There are a few things I don’t love but consider them small. I don’t like how elements of the JSON are all arrays except for the parent. I would prefer if they were string / integers and when there was a list to place them in an array. It’s a small price to pay but one that takes getting used to. I also don’t like how the parent has a ‘$’ key. But that’s also not a big deal.

Going the other way (JSON to XML) adds a bit of complexity. I’ve tried a number of modules that aim to do this, but the best I’ve found is js2xmlparser. I need to admit one thing upfront, you don’t exactly write one-to-one JSON to XML with this module. Instead it’s more of a Javascript Object, with some peculiarities. Here is an example:

Most of what happened in the code snippet is obvious but let me point out a few nice features. Using an array in a sub-element (line 37) will give them the appropriate tags in order. Secondly, nesting sub objects will give you the appropriate chain on nested tags. I found this easy to reason about and helped me to interface with the API naturally. Finally the ‘@‘ symbol is used to start a new parent. There are a host of other features in the library but I found these were all I needed to create quality XML payloads.

With these two packages you shouldn’t have any trouble dealing with XML. You should be able to wrangle any XML you get into sensible JSON with just one function and you should be able to make XML requests using Javascript objects without much trouble ( perhaps a little creativity).

Interfacing with SOAP APis

SOAP APIs are defined by a Web Service Definition Language (WSDL), that explains what a web service (API) has available (methods) and what those methods will return. It’s actually not a bad format (the API is clearly define) besides being painfully verbose. In languages that were built when WSDLs were popular, you can actually import the WSDL and a lot of the classes are generated for you, Loopback created a similar set of functionality for Node.js with their soap-connector. While this package works, I didn’t find it the most intuitive so I’ll share with you the method I used instead.

I’ve tried many iterations of SOAP API’s in Node.js and I found node-soap the easiest to work with while being the most comprehensive. With node-soap all you need is a WSDL, a method name, and a JSON payload and you’re on your way. Here is an example of how to do it with the Chase Payments API including how to find all the information you need:

WSDL methods:

Payload:

Returns:

Code:

Gotchas

When working with the node-soap library always use the proper name spacing and case. It is not friendly to errors and you will find yourself scratching your head. Finally if you have any questions about why something isn’t working the answer is in the WSDL. Every answer is there, it’s just a matter of finding it.

Wrap up

I won’t pretend like it’s easy to deal with XML/ SOAP based APIs in Node.js, I wrote this post to illustrate that it’s doable. There are other folks dealing with the same issues and its not likely to go away anytime soon. The more examples we post online the more we can help each other and make the web a better place.