Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Migration and Integration

Migrating SOAP Services to REST

Plan a safe SOAP-to-REST migration - map operations to resources, put a REST facade in front of the legacy service, route traffic gradually with the strangler pattern, and keep both interfaces working.

Plenty of organizations have a SOAP service that works, earns money and is somehow impossible to touch. At the same time, new consumers (mobile apps, partners, front-end teams) expect JSON over REST. A full rewrite is risky and slow; ignoring the demand means every new consumer has to learn SOAP.

The safer path is incremental migration. You put a REST facade in front of the SOAP service first, then replace operations behind it one at a time. Consumers see a modern API on day one, and the old system keeps running until nothing depends on it. This lesson walks through the plan and builds a working facade.

Step 1: map operations to resources

SOAP is operation-centric (verbs: GetOrder, CancelOrder). REST is resource-centric (nouns: orders). Migration starts with a mapping table.

SOAP operation REST resource and verb
GetOrder(orderId) GET /orders/{id}
ListOrders(customerId) GET /orders?customerId=...
PlaceOrder(...) POST /orders (returns 201 + Location)
UpdateOrderAddress(orderId, address) PATCH /orders/{id}
CancelOrder(orderId, reason) POST /orders/{id}/cancellation or DELETE /orders/{id}
CalculateShipping(...) POST /shipping-quotes (a computed resource)

Operations that do not fit a CRUD resource, such as CancelOrder with a reason, are modeled as a sub-resource (/cancellation) or an action resource. Do not force everything into four verbs; clear names matter more than purity.

flowchart LR
  C1["Mobile app"] --> G["REST facade (JSON)"]
  C2["Partner (SOAP)"] --> S["Legacy SOAP service"]
  G --> S
  G -.-> N["New REST implementation"]

The facade talks to the legacy service today; individual routes can be redirected to the new implementation later.

Step 2: build the facade

The program below has a legacy SOAP "inventory" service and a facade that exposes it as REST. The facade translates JSON to an envelope, calls the service, and turns the response and any fault into JSON with proper status codes.

Node.js A REST facade over a SOAP 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 consumers never see XML or the string NO_SUCH_SKU; they see a 404 with a JSON body. The facade also decided that the reservation creates something, so it answers 201. These decisions (status codes, resource names) are the real design work of a migration.

Step 3: the strangler pattern

Once the facade is live, you can replace the implementation behind individual routes, without any client noticing. The facade decides per route, or even per percentage of traffic, whether to call the legacy SOAP service or the new code. This is the strangler fig pattern: the new system grows around the old until the old can be removed.

Node.js Gradual cut-over with a traffic split

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.

Hash-based splitting keeps each customer on one side, so a user does not see data jump between systems from one call to the next. You raise percentNew step by step while comparing results and error rates, and drop to zero if something looks wrong.

Rules that make migrations work

  • Keep SOAP running until partners have moved. Announce a deprecation date and measure real usage per consumer.
  • Do not leak SOAP into REST: translate faults to status codes, dates to ISO 8601, and flatten XML structure into idiomatic JSON.
  • Handle statefulness and transactions explicitly. WS-AtomicTransaction has no REST equivalent; use sagas or idempotent operations instead.
  • Security changes shape. WS-Security tokens map to OAuth 2.0 / OpenID Connect or mutual TLS in the REST world. Plan the token exchange at the facade.
  • Test with recorded traffic: replay real SOAP requests through both paths and compare results before switching.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How should a SOAP operation like CancelOrder(orderId, reason) usually appear in REST?

    Actions that are not plain CRUD become sub-resources or action resources with clear names.
  2. 2. What does the strangler pattern do?

    The new system grows around the old one, route by route, until the legacy part can be retired.
  3. 3. A SOAP fault INSUFFICIENT_STOCK reaches the facade. Which HTTP status fits best?

    The request conflicts with the current state of the resource (stock), which is what 409 means.
  4. 4. Why use a hash of the customer id for traffic splitting?

    Consistent assignment prevents users from seeing data jump between old and new systems.

Summary

  • Map operations to resources, using sub-resources for actions that are not plain CRUD.
  • A REST facade translates JSON to SOAP and faults to proper status codes.
  • The strangler pattern replaces legacy routes gradually, with traffic splits and rollback.
  • Keep SOAP alive during deprecation, rethink security and transactions, and verify with replayed traffic.

Next: Integration Patterns: ESBs, Gateways and Message Translation