Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

How a SOAP Call Works

Follow one SOAP call from client to server and back: the HTTP POST, the Content-Type and SOAPAction headers, the XML body, with a working service and client on loopback.

A SOAP call is an ordinary HTTP request with an XML message in its body. If you can send a POST with fetch, you can call a SOAP service. This lesson builds a tiny service and a tiny client so you can see every byte that crosses the wire. Later lessons replace the hand-written parts with tools, but you will always be able to debug a call by reading these bytes.

The shape of one exchange

sequenceDiagram
    participant C as Client
    participant S as SOAP service
    C->>S: POST /calc (Content-Type: text/xml, SOAPAction)
    Note right of C: Body = Envelope with the request
    S->>S: Parse XML, find the operation, run it
    S-->>C: 200 OK, Envelope with the response

One request, one response, both are SOAP envelopes. Errors come back as a Fault inside an envelope.

Four things travel with every call:

  1. The URL of the service endpoint, for example https://bank.example/ws/accounts. A SOAP service usually has one URL for all its operations.
  2. The HTTP method: always POST, because a SOAP request carries a body.
  3. Headers: Content-Type says the body is XML, and in SOAP 1.1 a SOAPAction header hints which operation is wanted.
  4. The body: the XML envelope.

A calculator service

The classic first service adds two numbers. The server below reads the body, finds the operation name inside soap:Body, computes the answer and returns a response envelope. To keep the code short it finds values with simple pattern matching; real services use an XML parser, which you build in XML Basics for SOAP.

Node.js A SOAP calculator and its client

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.

Read the output from top to bottom: the server logs the method, the path and the SOAPAction header, the client prints the HTTP status and the content type, then the whole response envelope, and finally the one value it wanted. In a real project a library does the last step for you, but the envelope is exactly what you see here.

Why POST and why one URL?

REST services spread operations across many URLs and methods (GET /accounts/7, DELETE /accounts/7). SOAP does the opposite: the URL names the service, and the operation is named inside the message (the first element of the body). That has consequences:

  • Every call is a POST, so HTTP caches and CDNs cannot cache SOAP responses by default.
  • Firewalls and proxies cannot tell what an operation does from the URL; they need to read the XML.
  • The SOAPAction header (SOAP 1.1) lets infrastructure route a message without parsing the body.

The HTTP status codes

SOAP over HTTP maps its results to HTTP codes in a specific way:

Situation HTTP status Body
Call succeeded 200 Response envelope
The client sent a bad message 400 (1.2) or 500 (1.1) Envelope with a Fault
The server failed 500 Envelope with a Fault
Wrong URL or service missing 404 Anything, often HTML

In SOAP 1.1 every Fault comes with status 500, even when the client was at fault. The status code only tells you "something went wrong"; the Fault inside tells you what. SOAP Faults covers it fully.

Seeing a failure

Let us call the same service with a broken body and see what a careless service does. This is a good habit: always try the bad path.

Node.js What happens with a bad request

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.

A client must therefore check both the HTTP status and the content of the body. A 500 response with a readable Fault is not a network failure; it is the service explaining a problem.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which HTTP method does a SOAP request use?

    A SOAP request carries an XML body, so it is always an HTTP POST. The operation is named inside the body, not by the method.
  2. 2. Where does a SOAP service find out which operation was requested?

    The URL names the service; the operation is the first child element of the Body. SOAPAction is an extra hint for routing.
  3. 3. In SOAP 1.1 over HTTP, which status does a Fault normally come with?

    SOAP 1.1 returns Faults with HTTP 500, even for client mistakes. SOAP 1.2 can use 400 for sender faults.
  4. 4. Why are SOAP responses usually not cached by HTTP caches?

    HTTP caches rely on GET and distinct URLs. SOAP sends POST requests to one endpoint, so caches cannot key on the operation.

Summary

  • A SOAP call is an HTTP POST whose body is an XML envelope; the answer is another envelope.
  • One URL serves the whole service; the operation is named inside the body.
  • Content-Type and (in 1.1) SOAPAction headers accompany the message.
  • Failures come back as a Fault, normally with HTTP status 500.
  • Clients must check the HTTP status and the body.

Next: SOAP 1.1 vs 1.2 and Transports