skip to content

An insurer runs many partner-facing SOAP services; how would you decide which to migrate to REST and which to keep on SOAP?

level: principalimportance: nice to knowfreq 9%

answer

  1. service by service, not estate-wide
  2. who pays for the change
  3. which WS-* features are really used
  4. partners' generated clients
  5. RPC tunnel is not REST

basics

~20 s

Decide service by service: migrate where partners want it and the service uses plain request-response, and keep SOAP where partners' certified clients depend on the WSDL or where message-level security, reliable messaging or queue transport is genuinely in use.

solid answer

~40 s

I would inventory the estate before choosing anything: for each service, who calls it, how many partners hold generated clients from its WSDL, and which WS-* features are actually used rather than merely configured. A service that is plain request-response over TLS, with partners asking for JSON, is a good migration candidate. A service whose partners verify WS-Security signatures and archive signed messages, rely on reliable messaging, or call it over a queue keeps SOAP, because REST would make me rebuild those guarantees by hand. Migration cost falls mostly on partners, who must rebuild and re-certify their clients, so I would migrate where they gain something - and make each new API genuinely resource-oriented, not the same operations re-posted as JSON. Retirement then needs a published sunset with partners, not a switch-off.

go deeper

for a junior

Know that SOAP services often stay because partners built clients from their WSDL, and that moving them costs those partners real work.

for a middle

Explain which features make a SOAP service hard to replace: typed faults, message-level signatures, reliable messaging and queue transport.

for a senior

Show how you would inventory an estate and pick a low-risk pilot, measuring partner adoption before committing further services.

for a principal

Own the trade-off: provider savings against partner cost, regulatory mandates, and a sequenced sunset that never turns a technology choice into a partner incident.

## Why this is a judgement call There is no rule that says when a SOAP estate should move. The answer depends on partners you do not control, features you may or may not use, and the money and attention each migration takes away from other work. A principal answer shows a method for deciding and names the traps, rather than a verdict. ## Start with an inventory For each SOAP service, record: - **Consumers.** How many partners call it, and how many of them generated a client from its WSDL and passed a certification against it. - **WS-* features in real use.** Whether signatures are verified and stored, whether messages pass through intermediaries, whether WS-ReliableMessaging or WS-AtomicTransaction are active, whether any partner reaches it through a queue binding. Configured but unused features do not count. - **Traffic shape.** Mostly writes between known partners, or reads that a new class of client - a web or mobile app - wants with caching. - **Pain.** Interop problems, support tickets, slow onboarding of new partners, cost of keeping XML specialists and toolchains. - **Change rate.** How often the contract changes. A service whose WSDL has not moved in years costs little to keep; one that changes every quarter forces every partner to regenerate clients each time, which is where a looser contract can pay off. ## Criteria for each service | Signal | Suggests migrating | Suggests keeping SOAP | |---|---|---| | Partner demand | Partners ask for JSON and HTTP-native errors | Partners have certified WSDL clients and no wish to change | | Security | TLS to the edge meets the requirement | Signed or encrypted message parts must survive intermediaries or be archived | | Delivery | Request-response over HTTP | Queue transport or WS-ReliableMessaging in use | | Reads | Read-heavy, cache-friendly data | Mostly writes and transactions | | Contract | A looser, evolving contract is acceptable | Strict schema validation on both sides is valued | | Regulation | No mandated format | A regulator or industry body mandates the SOAP interface | ## Sequencing a migration 1. **Pick a pilot** with low partner count, no message-level security and clear demand. 2. **Design the new API as a resource-oriented API**, with its own description, status-code error model and caching - not a mechanical translation of operations. 3. **Offer both for a period** and let partners move on their own release cycles; running two styles side by side is a design topic of its own. 4. **Measure** adoption and support load before choosing the next service. 5. **Publish a sunset** for the SOAP interface only when remaining traffic and partners are known, and keep its WSDL frozen until then. ## Who pays The provider writes the new API once; **every partner** rebuilds a client, retests and often recertifies. A migration that saves the provider a toolchain but costs fifty partners a project each is a poor trade unless they gain something - simpler onboarding, lower latency, data they could not get before. ## What you lose by migrating - **Typed faults** declared in the WSDL, which partners' generated code turned into typed errors. - **Message-level signatures**, unless you adopt another signing scheme and get every partner to verify it. - **Transport independence** for partners who reach the service through queues. - **Strict validation** that caught malformed messages at the edge. ## Traps - **The RPC tunnel with JSON.** Re-exposing every operation as `POST /operationName` with a JSON body keeps SOAP's one-method shape, gains none of HTTP's caching or status semantics, and drops the typed contract partners relied on. It is neither SOAP nor REST. - **Big-bang retirement.** Switching off SOAP on a date before partners have moved turns a technology decision into a partner incident. - **Migrating the stable core first.** The services that never change and work well gain least from migration. - **Ignoring the mandate.** Where a regulator or industry body specifies the SOAP interface, the decision is not the provider's to make. ## A defensible default Keep SOAP where it is the shared contract of an ecosystem or where its message-level features are genuinely used; build new partner capabilities resource-oriented from the start; migrate existing services only where partners gain enough to bear the cost of moving.

  • A partner says it will move to your REST API only if responses stay signed. What are your options?
    Either keep that partner's flow on SOAP with WS-Security, or adopt a signing scheme for the JSON payloads that both sides implement and verify. The second is new work for both parties and must be agreed and tested like any contract change, so the partner's requirement is a strong signal that this service should stay on SOAP for now.
  • How do you know when the SOAP interface can finally be switched off?
    When traffic data shows no remaining callers, or only callers who have agreed a date, and the sunset was announced long enough before for partners to plan a release. Monitoring per partner, not per endpoint, is what makes that visible.

saying these in an interview costs you the question

  • Migrate the whole estate at once so only one style has to be supported.
  • Re-exposing each SOAP operation as POST with a JSON body makes the API RESTful.
  • Migration costs only the provider, because partners just switch URLs.
  • Message-level signatures can be dropped because TLS gives the same guarantee.
  • A SOAP service should be retired as soon as a REST version exists.