How to Perform SOAP Requests With Node.js

Sharing is Caring

SOAP is basically an XML based API that existed before the REST API existed. SOAP stands for Simple Object Access Protocol – it’s a mostly legacy protocol that was designed for doing remote api requests in a language independent way.

SOAP was designed by Microsoft to replace a couple of techniques that didn’t really work very well on the internet and over networks (DCOM & CORBA). It really flourished in large enterprises to the point that many companies have at least one SOAP server. For example, I’ve used SOAP a lot with Salesforce.

Why use SOAP?

If you can use a normal REST API and avoid doing SOAP requests, you should stop reading here and use that approach instead. If you have experience working in a large company or an older company you’ll probably have quite a bit of experience connecting to an old SOAP Service written in early .NET or Java.

Integrating a SOAP server into some languages can be really difficult because it is not tolerant of errors at all. In JavaScript, we don’t really get a lot of the complexity hidden away like we might be in C#.NET without having to use a really heavy library.

What is a SOAP Server?

A SOAP server will provide you a WSDL file that contains a schema in XML that defines what the server can do and the actions that it will accept. WSDL stands for Web Services Description language.

What is a SOAP Request?

The SOAP message is simply an XML document. A SOAP request has three parts:

an envelope which basically describes how the message is structured and how to process it
encoding rules and datatypes
conventions for procedure calls & responses.

A soap response will look something like this:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2001/12/soap-envelope" 
SOAP-ENV:encodingStyle="http://www.w3.org/2001/12/soap-encoding" >
   <SOAP-ENV:Body xmlns:m="http://www.example.org/message" >
      <m:Message>
         <m:Subject>This is a subject..</m:Subject>
         <m:Body>Hello email reader...</m:Body>
      </m:Message>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

So, how do we connect to a SOAP endpoint from Node.js?

There’s a node module conveniently called “soap” that can do a lot of the heavy lifting for us and help abstract away a lot of the complexity of SOAP. This soap module can be a client or be a server if we wanted to build one. I’m not sure why anyone would want to build a SOAP based API at this point but you definitely could.

To use it in our project we’ll need to run the following command from the terminal

npm i soap

Installing the node module will then update our package.json and our package-lock.json.

To build a soap based client we’ll need to do something like the following in our project:

'use strict'

const soap = require('soap')
const wsdlUrl = 'http://www.chemspider.com/MassSpecAPI.asmx?WSDL'

// passing in overridePromiseSuffix because some of the endpoints end
// with "Async" which breaks promisify.
soap.createClientAsync(wsdlUrl, {overridePromiseSuffix: 'Promise'})
  .then(client => {
    client.GetDatabasesPromise({})
      .then(results => {
        // results is an array with only one item which then has an array called "string".
        const databases = results[0].GetDatabasesResult.string

        // normally we would do some sort of processing or something.
        console.dir(databases)
      })
  })

The soap module is doing a lot of magic behind the scenes to create a lot of the methods for us. In a lot of languages, you end up having to create classes that match exactly to be able to use SOAP.

Wrapping It up

SOAP is really an old legacy API technology that worked really well back in the early 2000s. If you can avoid it you should, but it’s definitely possible to use the soap module and have it do a lot of the work for you.

Sharing is Caring