Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 ยท Migration and Integration

Versioning and Evolving Legacy SOAP Services

Change a SOAP service without breaking its consumers - compatible vs breaking changes, namespace and endpoint versioning, the tolerant reader, deprecation, and idempotency keys for safe retries.

The moment a second team calls your SOAP service, you lose the freedom to change it casually. A renamed element, a new required field or a different error code can stop a partner's production system at 3 a.m. SOAP's strict contracts make this both better (the contract tells you exactly what you promised) and worse (generated clients break on small differences).

This lesson gives you a practical policy for evolving a service: what counts as a breaking change, how to publish a new version beside the old one, how consumers should be written to survive harmless changes, and how to make retries safe while everything changes around you.

Compatible and breaking changes

Change Safe?
Add a new operation Yes: existing clients never call it
Add an optional element at the end of a response Usually yes (clients must tolerate it, see below)
Add an optional element to a request Yes
Add a required element to a request No: existing requests become invalid
Remove or rename an element or operation No
Change a type (int to string, date to dateTime) No
Narrow allowed values (shorter maxLength, fewer enum values) No for requests; widening is safe
Change the order of elements in a sequence No
Change a fault code or message that clients match on No

Strict generated clients are the reason even "harmless" additions can break: a client built with a schema-validating binding may reject an element it has never heard of. That is why the rule of thumb is: be conservative in what you send, tolerant in what you accept.

Publishing a new version

When you must break compatibility, run both versions side by side. The two common ways to say "which version" are:

  • Namespace versioning: the target namespace carries the version, e.g. urn:shop:orders:v1 and urn:shop:orders:v2. The message itself says which contract it follows, and a single endpoint can serve both.
  • Endpoint versioning: separate URLs, /orders/v1 and /orders/v2, each with its own WSDL.

Namespace versioning is the traditional SOAP approach because the namespace is part of every element's name; endpoint versioning is simpler for routing, gateways and metrics. Many teams combine them, which keeps the two in step.

Node.js One endpoint, two namespace versions

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.

Old clients keep sending v1 and keep working, while new clients move to v2 at their own pace. The unknown version gets a precise fault instead of a confusing parse error; SOAP even has a standard fault code, VersionMismatch, but that one strictly refers to the SOAP envelope version, so many teams use a custom code for contract versions. We reused it here only for brevity.

The tolerant reader

On the consuming side, write your parsing so that harmless changes do not break you. This is Postel's law applied to messages and it is called the tolerant reader pattern:

  • Read only the elements you need, by name, not by position.
  • Ignore elements you do not recognize.
  • Treat optional elements as absent without failing.
  • Do not validate against a schema stricter than the contract requires; avoid generating clients that fail on unknown elements, or turn that option off.
Node.js Strict reader vs tolerant reader

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 strict reader breaks the day a field is added; the tolerant reader even picks up the new field when you decide you want it.

Idempotency: making retries safe

Changing systems means more timeouts, restarts and retries, and retries are dangerous for operations that change state. If a "place order" call times out, the client does not know whether the order was created. Calling again may create a duplicate.

The fix is an idempotency key: the client generates a unique value per logical operation (often in a SOAP header or a dedicated element) and sends the same key on every retry. The server remembers the key and returns the stored result for repeats.

Node.js An idempotent PlaceOrder

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.

In a real service, the key store must be durable (a database table with a unique constraint), keys should expire after a sensible period such as 24 hours, and the server should also compare the request payload: the same key with different content is a client bug and deserves a fault.

A deprecation routine

  1. Announce the end-of-life date, in the WSDL documentation, release notes and by email to registered consumers.
  2. Measure: log version and consumer id per call so you know who still uses what.
  3. Warn: add a response header or a documented element, and contact heavy users directly.
  4. Brown-out: shortly before shutdown, return faults for an hour on a set day so hidden users surface.
  5. Retire the version, keeping the fault message helpful ("v1 was retired on ... use v2").

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which change to a request message is breaking for existing clients?

    Old clients do not send the new required element, so their requests become invalid.
  2. 2. What does namespace versioning mean?

    The namespace is part of every element name, so it unambiguously identifies the contract version.
  3. 3. What is the tolerant reader pattern?

    A tolerant consumer survives additive changes because it does not depend on exact structure.
  4. 4. Why does a retry of PlaceOrder need an idempotency key?

    After a time-out the client cannot know whether the first attempt succeeded; the key makes retry safe.

Summary

  • Adding operations and optional elements is generally safe; removing, renaming, retyping and new required fields are breaking.
  • Run old and new versions side by side, using namespace or endpoint versioning.
  • Consumers should be tolerant readers; producers should be conservative senders.
  • Idempotency keys make retries safe for state-changing operations.
  • Retire versions with announcement, measurement, warnings and a brown-out.

Next: Project: A Currency Conversion Service