Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Building and Consuming Services

Building a SOAP Client in Node.js

Write a reusable SOAP 1.1 client with fetch - build envelopes, set SOAPAction, read responses, turn faults into exceptions, add timeouts and safe retries, and call it against a live loopback service.

Consuming a SOAP service means doing the mirror image of what the server does: build an envelope, POST it, read the response, and decide whether you got an answer or a fault. A generated client hides this behind typed methods like client.add(2, 40). Behind those methods there is always the same sequence, and understanding it helps you debug the day a call returns something unexpected.

In this lesson you will write a small client class that handles the parts every production client needs: the right headers, XML escaping, faults as exceptions, timeouts, and carefully limited retries.

The request your client must send

A SOAP 1.1 call over HTTP needs three things:

  1. POST to the service endpoint.
  2. Content-Type: text/xml; charset=utf-8.
  3. A SOAPAction header (quoted string, may be empty ""). Many services ignore it, but some route on it, and WS-I Basic Profile requires it to be present.

SOAP 1.2 changes this: the content type becomes application/soap+xml; charset=utf-8; action="..." and there is no separate header.

The body is an envelope. For document/literal wrapped services, which are the norm, the first child of Body is named after the operation and carries one element per parameter.

A reusable client

The service in this example is a tiny in-memory "greeter" that we start first, so that the client has something real to talk to. Focus on the SoapClient class: it is the part you can lift into your own code.

Node.js SoapClient with faults as exceptions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Two details are easy to miss. First, esc() runs on every parameter, so Ada & Grace is sent as Ada & Grace; forgetting this breaks the XML the moment a user types an ampersand. Second, the response parser un-escapes text on the way back, so the caller sees real characters.

Timeouts and retries

Network calls fail in ways that have nothing to do with SOAP: connections reset, servers hang, gateways return 502. A client needs a time limit on every call (AbortSignal.timeout) and a retry policy that distinguishes safe from unsafe repetition.

  • Retry on network errors, time-outs and 503/502/504 responses.
  • Do not retry Client faults: sending the same bad request again will fail the same way.
  • Only retry operations that are idempotent (reads, or writes protected by an idempotency key), otherwise a retry after a lost response may charge a card twice.
  • Wait between attempts, increasing the delay each time and adding a little randomness.
Node.js Retries with backoff against a flaky service

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first two attempts get a 503, the third succeeds. In real code, add random jitter to the delay so many clients that failed together do not all retry at the same moment.

Log the SOAP envelope you send and receive while developing, and turn it down in production. Most "SOAP is broken" mysteries disappear once you can see the actual XML on both sides.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which header content type does a SOAP 1.1 request use?

    SOAP 1.1 uses text/xml. SOAP 1.2 uses application/soap+xml.
  2. 2. Why must a client escape parameter values before inserting them into the envelope?

    Values are text nodes in XML, so markup characters must be written as entities.
  3. 3. Which response should a client NOT retry automatically?

    A Client fault means the request itself is wrong; repeating it fails identically.
  4. 4. Why should write operations be retried only with an idempotency key?

    With a key, the server recognizes the repeated request and returns the original result instead of doing the action twice.

Summary

  • A client POSTs an envelope with Content-Type: text/xml and a SOAPAction header (SOAP 1.1).
  • Escape every value that goes into XML and unescape what comes back.
  • Convert faults into exceptions that carry code, message and HTTP status.
  • Always set a time-out; retry only transient failures, with backoff, and only idempotent operations.

Next: Dynamic Clients from a WSDL