Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Projects and Practice

Project: A Currency Conversion Service

Build a complete SOAP web service in Node.js - operation registry, generated WSDL, validation, faults, a client and automated checks - and see every concept from the course working together.

In this project you will build a complete, small SOAP service from scratch: a currency conversion service with two operations, a generated WSDL, input validation, proper faults and a client that discovers the operations from that WSDL. It touches nearly every idea in the course: envelopes, namespaces, contracts, faults, escaping, testing.

Everything runs inside the editor with plain Node.js: the service listens on loopback and the program calls itself. Build it in the three stages below, then try the extensions at the end.

The design

Item Decision
Namespace urn:fx:v1
Operations ListCurrencies(), Convert(amount, from, to)
Style document/literal wrapped, SOAP 1.1
Errors Client faults for bad input with a detail code; Server fault for anything unexpected
Contract WSDL generated from the operation registry, served at ?wsdl

The central idea is a registry: one table describing each operation (parameters, types, handler). The WSDL, the validator and the dispatcher are all driven from it, so the contract cannot drift away from the code.

One registry, three jobs

Registry Operations, params, types
WSDL Generated from the registry
Validator Checks every request
Dispatcher Calls the handler

Change the registry and all three follow.

1 / 2

Stage 1: the service

Node.js Stage 1 - registry, WSDL and dispatcher

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 line by line. Every failure is a Client fault with a machine-readable errorCode, so callers can react in code instead of parsing English. The WSDL lists exactly the operations in the registry.

Stage 2: a contract-driven client

A client should not hard-code operation names that the WSDL already lists. This stage shows the idea in the smallest possible way: take the list of operations from the contract and build one function per operation. We use a pre-generated WSDL string here, so the stage runs on its own.

Node.js Stage 2 - a client built from the contract

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.

Stage 3: extensions to try yourself

Copy Stage 1 into the editor and extend it. Each item reinforces one chapter of the course:

  1. Add a header. Require a <apiKey> SOAP header and return a Client fault with code UNAUTHORIZED when it is missing.
  2. Add a third operation, GetRateHistory(currency, days), that returns repeated <point> elements. Check that the generated WSDL picks it up without any other change.
  3. Add idempotency: make Convert accept an optional requestId and cache the answer.
  4. Write tests with node:test (see Testing SOAP Services) for each error code.
  5. Put a REST facade in front as described in Migrating SOAP Services to REST: GET /rates/USD/EUR?amount=100.

When something does not work, print the raw request and response. Ninety percent of SOAP bugs are visible in the first look at the XML.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why generate the WSDL from the operation registry?

    One source of truth feeds the WSDL, validation and dispatching, so they stay consistent.
  2. 2. What is the benefit of a machine-readable errorCode in the fault detail?

    Messages change and may be translated; stable codes let clients react reliably.
  3. 3. What should the service return for an unexpected internal exception?

    Internals are for logs; callers get a generic fault they can quote to support.
  4. 4. Which check protects the parser against entity-expansion attacks?

    SOAP messages never need a DTD, so refusing them removes the whole attack class.

Summary

  • A registry of operations can drive the WSDL, validation and dispatch from one source of truth.
  • Return Client faults with stable error codes for bad input and a generic Server fault for internal errors.
  • Escape output, limit input size and reject DTDs.
  • Clients can generate their methods from the contract's operation list.

Next: Project: A REST-to-SOAP Gateway with Token Authentication