SOAP Migration Workbench
Turn a WSDL into a REST design with an OpenAPI file, adapter code and parity tests. Switched off unless your site enables it.
The SOAP Migration Workbench takes a WSDL and proposes a REST API for it. It gives you an OpenAPI file, adapter code that puts the REST API in front of the SOAP service, and parity tests that check the two answer the same way. It lives at /soap.
It is switched off by default. If you don't see SOAP Workbench in the product switcher, your site does not have it, and /soap takes you to the Home page. You can still read a WSDL without it. Open it in the API Map or add it to Contract Graph, and either one shows it as a proposed REST design.
The rest of this page applies only where the workbench is switched on.
Adding a service
The workbench works on a programme, which is the set of SOAP services you are migrating. Add a service from the sidebar in one of four ways:
- Drop WSDL and XSD files on Drop WSDL and XSD files. Schemas dropped together with a WSDL are attached to it.
- Click Paste, paste the WSDL text, then click Add service.
- Enter a WSDL URL and click Fetch.
- Load the Bank sample to look around first.
A JSON file is turned away, because OpenAPI and Postman files belong in the API Map.
A programme holds up to 300 services, and a WSDL can be up to 25 MB. Programmes are kept in this browser. Export one from the sidebar as soap-migration-programme.json to back it up or move it.
The tabs
Each service has five tabs, and opens on Design.
| Tab | What you do there |
|---|---|
| Contract | Read the WSDL as it stands: each operation with its input, output, faults and SOAPAction |
| Design | Review the proposed REST endpoint for each operation |
| OpenAPI | Download the design as an OpenAPI 3.0.3 file |
| Adapter | Download code that serves the REST API in front of the SOAP service |
| Parity | Compare the SOAP and REST answers for each operation, and download tests |
Design
Each SOAP operation gets a proposed method, path and summary, with a confidence figure. Expand a row to see why the proposal was made and anything in the schema that was ambiguous. You can edit the method, path and summary in place. Back to the proposal undoes your edits.
Give each operation a status as you work: Proposed, Reviewed, Approved, Migrated or Skipped. The Needs review filter shows what is left. Above the table you can set the Base path, which is /v1 by default, and the style of Property names: camelCase, snake_case, or as written in the XSD.
OpenAPI
Choose YAML or JSON, then Copy or Download. Open in API Map opens the design there. Add to Contract Graph puts it in a workspace you choose.
Adapter
The Adapter tab generates a project for one of three targets and downloads it as a zip. It opens on Node.
| Target | What you get | Run it with | How far it has been checked |
|---|---|---|---|
| Node | One file with no dependencies, for Node 18 or newer | node adapter.mjs | Started and called end to end by the workbench's own tests, against a stand-in SOAP service |
| ASP.NET Core | A minimal API for .NET 8 | dotnet run | Compiled once by hand, not by the tests. Build it before relying on it |
| Spring Boot | A Spring Boot 3 project for Java 17 | mvn spring-boot:run | Not compiled by the tests. Build it once before relying on it |
Each project needs the address of the real SOAP service. The tab shows the exact option for the target you picked, and the project's README repeats it.
Parity
Enter the SOAP endpoint and the address of the REST API. Pick an operation to see the SOAP envelope and the REST request side by side, each of which can be copied as XML or cURL. Send calls the REST side. Download parity tests gives you a zip of test cases, with the command that runs them in Node.
Coverage
Coverage, at the top of the sidebar, shows how far the whole programme has come: services, operations, and the share migrated or retired. Paste call counts per operation, one operation, calls pair per line, and it also shows how much of your traffic is covered. The Queue then lists the operations still to do, busiest first.
The REST bridge
While you work on a design, the workbench can serve it as a live REST API. Each REST call is turned into a SOAP request to the real service, and the reply comes back as JSON. The service header says live at an address when the bridge is running, and not hosted when it is not.
The WSDL file itself stays in your browser. To run the bridge, though, the design goes to a server run by your site: the routes, the schemas and the SOAP endpoint's address. It is the one part of Vizroute that sends your work to a server.