Saudi banks carry a large estate of SOAP services — WSDL-defined operations built over the past 15 to 20 years that represent the accumulated business logic of core banking, payment processing, trade finance, and customer onboarding. These services work. They have been tested by every transaction the bank has processed since they were deployed. Their WSDLs document every operation, input type, and fault condition with a precision that most REST API definitions never achieve. What they do not do is speak the language that digital channels, fintech partners, and Open Banking consumers expect: JSON payloads, OAuth2 bearer tokens, HTTP status codes, and OpenAPI documentation they can explore without understanding XML namespace resolution.
What the decision is
The SOAP-to-REST modernisation decision presents three options. Wrap: place a REST facade in front of the existing SOAP service, leaving the backend unchanged. The facade translates REST calls to SOAP calls and SOAP responses to JSON responses. Rewrite: build a new service that implements the same business logic in a modern stack and retire the SOAP service. Expose as-is: make the SOAP service accessible to new consumers without change — requiring those consumers to understand WSDL, XML, and SOAP fault handling themselves.
The expose-as-is option is not a real option for consumer-facing APIs. No digital channel team will build a mobile app against a SOAP backend in 2026, and no fintech partner will accept a WSDL as documentation for an Open Banking integration. It remains a viable internal option when the only consumers are other enterprise systems that already have SOAP integration capabilities, but even then it defers rather than solves the modernisation problem.
The rewrite option is seductive precisely when the SOAP service is most painful to work with — when it is complex, underdocumented, or slow. But complexity, inadequate documentation, and slow response times are not arguments for rewriting; they are symptoms of the same underlying problem that a rewrite will reproduce unless the root cause is addressed first.
The rewrite option carries a risk profile that organisations consistently underestimate: the SOAP service’s behaviour is the specification. Every edge case in 15 years of WSDL operations — the SOAP fault that gets returned for a duplicate payment reference, the field that must be empty rather than absent for a specific account type, the response timing behaviour that downstream systems have been coded to work around — is implicit in the existing implementation and invisible in any documentation. A rewrite that does not replicate all of this behaviour faithfully will produce production incidents that the SOAP service has never experienced. Wrapping avoids this risk entirely: the SOAP service continues to handle the business logic, including all its accumulated edge case behaviour, while the REST facade changes only the interface.
The regulatory angle
SAMA’s Open Banking Framework specifies that consumer-facing APIs must conform to the Financial-grade API Security Profile 2.0 (FAPI 2.0). This requirement applies to the API that the consumer sees — the REST facade — not to the backend that the facade calls. A SOAP service that authenticates via WS-Security UsernameToken with BasicAuth credentials over TLS is compliant for internal integration; it is not compliant as a consumer-facing Open Banking endpoint regardless of what any architecture diagram says. The facade must implement FAPI 2.0: OAuth2 authorisation code flow with PKCE, Demonstrating Proof-of-Possession (DPoP) for bearer tokens, and the required FAPI response headers (x-fapi-interaction-id, x-fapi-auth-date) on every response.
This distinction matters for project scoping. The FAPI 2.0 compliance work is not trivial. It requires a compatible identity provider, certificate infrastructure for DPoP, and configuration of the API gateway layer. It is not a two-day configuration task. If the project plan for a SOAP-to-REST wrapper does not include FAPI 2.0 compliance as an explicit work item — with its own timeline, its own infrastructure dependencies, and its own compliance testing — the project will either miss the regulatory requirement or delay it to a follow-on phase that may not get funded. Include it in the initial scope, budget for it accordingly, and test it against the SAMA Open Banking conformance suite before the facade goes live on a consumer-facing channel.
The business trade-off
A well-designed REST facade extends the operational life of a proven SOAP backend by five to ten years at a cost that is typically 10 to 20 percent of the cost of a backend rewrite. The backend continues to handle business logic it has been doing correctly for years. The facade handles the interface concern. New digital channels, new fintech partners, and new regulatory requirements are addressed at the facade layer — not by modifying a production backend that carries payment processing risk.
A poorly designed wrapper creates a different problem: two API surfaces to maintain simultaneously, with coupling between them that makes changes to either difficult. The failure mode is a wrapper that exposes the SOAP backend’s internal model through the REST interface — JSON keys that are XML element names with namespace prefixes stripped, REST responses whose structure mirrors the SOAP response tree rather than the resource model, error messages that contain SOAP fault codes in JSON strings. A REST API designed this way is a SOAP API in disguise, and it combines the development friction of SOAP with the operational complexity of a REST layer on top of it.
The design discipline that prevents this is a contract-first approach: the OpenAPI specification is written first, without reference to the WSDL, as if the SOAP backend did not exist. The specification defines what developers consuming the REST API will see. Only after the specification is agreed does the implementation work begin, with the WSDL as a reference for the backend behaviour but not as the template for the REST design. This sequence requires more discipline to maintain than starting from the WSDL and deriving the REST shape, but the result is an API that reads as a native REST service and can survive a backend replacement without breaking its consumers.
What leadership must own
The SOAP-to-REST wrapper project is often scoped as a platform engineering initiative with a clear technical deliverable: a REST endpoint that wraps a SOAP backend. The decisions that determine whether that deliverable has durable value are not technical; they are governance decisions that require VP-level ownership.
The first is OpenAPI contract ownership. The contract is the commitment to consumers. When the SOAP backend changes a field type, when a new operation is added, when an existing fault code changes meaning, the OpenAPI contract must be updated in a controlled way. This requires a named owner who reviews backend changes against the contract, determines what is a breaking change, and manages the versioning process. Without a named owner, the contract drifts from the implementation, and consumers who relied on the published specification find their integrations broken by changes they were not notified about.
The second is developer portal governance: who approves the publication of new API versions, who manages the subscription tiers and rate plans, and who is responsible for the API documentation that fintech partners and third-party developers read. These are product management responsibilities that do not naturally fall to the integration engineering team. If they are not explicitly assigned, the developer portal becomes an orphaned catalogue of outdated specifications.
The third is a deprecation timeline and auth migration budget for direct SOAP consumers. The wrapper creates a migration path for new consumers. Existing SOAP consumers — other internal systems that have been calling the SOAP backend directly for years — must migrate to the REST facade before the SOAP interface can be decommissioned. This migration requires effort from the consuming teams, not just the integration team. It will not happen unless it is mandated with a deadline and funded in the consuming teams’ roadmaps. Setting a SOAP deprecation deadline without the authority and budget to enforce it produces a situation where the SOAP endpoint is nominally deprecated but continues to receive traffic indefinitely, and the integration team maintains two interfaces in perpetuity.
For the engineering depth behind these decisions — WSDL analysis and operation-to-verb mapping, ACE ESQL envelope construction, IBM API Connect assembly policies, SOAP fault to RFC 7807 mapping, FAPI 2.0 configuration, the strangler fig migration pattern, and the production checklist — see the companion Lab article: Legacy Integration: SOAP-to-REST API Modernisation.