Import a WSDL for SOAP-to-REST Conversion

Overview

Importing a Web Services Description Language (WSDL) contract is the initial step in the Publish flow for creating a REST API from an existing SOAP service. The platform ingests the WSDL to understand the SOAP service's operations, messages, and data types.

From this contract, the platform automatically:

1. Parses the operations and their associated XML Schema Definitions (XSDs).
2. Creates an immutable, canonical model of the contract for each operation.
3. Infers a draft service configuration, including a backend endpoint, REST-ful resource paths, and HTTP methods.
4. Generates sample REST and SOAP payloads for testing and verification.

This process provides a fully configured starting point, minimizing the manual effort required to publish a new REST API proxy for a SOAP backend. This document describes the WSDL import process for the Publish (SOAP-to-REST) direction.

How to Provide the WSDL

To begin, navigate to Onboarding → Upload WSDL. The platform provides three methods for supplying the WSDL contract.

Method	Description	Notes
By file	Upload a .wsdl file directly from your local machine.	If the WSDL uses import to reference external XSDs, you must upload those schema files in the same operation for all types to be resolved.
By URL	Provide a publicly accessible URL pointing to the WSDL.	The platform fetches the WSDL and transitively resolves xsd:import and xsd:include directives. Cycle protection is in place to handle circular dependencies.
Pasted XML	Paste the raw XML content of the WSDL directly into the text area.	This method is useful for evaluating a WSDL snippet or when the contract is not accessible via a direct URL, such as when it is behind authentication.

Note: For WSDLs that reference XSDs at unreachable URLs (e.g., in an air-gapped environment), the platform cannot fetch them. In this scenario, you must use the By file method and upload the WSDL and all dependent XSDs together. This is a known limitation as of v1.0.

WSDL Parsing and Contract Generation

Upon import, the platform performs a comprehensive analysis of the WSDL and its associated schemas.

How It Works

1. The importer first validates the XML structure of the provided WSDL.
2. It then parses the wsdl:definitions, identifying each portType and operation.
3. For each operation, it analyzes the input, output, and fault messages, supporting both document/literal (wrapped and bare) and rpc/literal styles.
4. The parser traverses the entire wsdl:types schema tree for each operation, resolving a wide range of XSD constructs, including:
   • Compositors: sequence, choice, all
   • Type derivation: complexType, complexContent (extension and restriction), simpleContent
   • Groups: group, attributeGroup
   • Schema composition: import, include, redefine
   • Advanced features: substitution groups, xsi:type variants, list, union, wildcards (any, anyType), attributes, mixed content, and restriction facets (enumeration, pattern, etc.).
5. WSDL-declared wsdl:fault contracts are parsed to model SOAP fault details for each operation.
6. Finally, the platform creates an immutable snapshot of the contract for each operation. This snapshot includes a checksum and the parser version, ensuring that any future regeneration of the service from this artifact is deterministic.

For a complete list of supported SOAP and XSD features, see SOAP & XSD Support.

Namespace Repair

The importer can automatically apply namespace repair for WSDLs with missing or inconsistent namespace declarations. This allows contracts that would otherwise fail validation to be successfully onboarded. When a repair is applied, a note is added to the import summary detailing the changes made.

Inferred Service Configuration

After parsing the WSDL, the platform generates a draft configuration to accelerate the publishing process. You can accept these suggestions or override them before generating the service.

The following settings are inferred:

• Backend endpoint: The SOAP service URL is extracted from the soap:address location in the WSDL.
• SOAP version: The platform detects whether the binding uses SOAP 1.1 or SOAP 1.2.
• Auth hint: A recommended authentication type is suggested if it can be determined from the WSDL's binding or policy elements.
• Namespace: The targetNamespace of the service is captured.
• Draft identity: A suggested serviceKey, serviceName, and environment are generated.
• REST method/path per operation: The platform infers RESTful HTTP methods (e.g., GET, POST) and resource paths based on common SOAP operation naming patterns (e.g., get..., list..., create...). If an inference would cause a collision, the unique operation key is used as a fallback. Placeholders in the path (e.g., for an ID) are mapped to matching field names from the request schema (e.g., ById in the operation name might map to a citizenId field in the request).
• Capability notes: The importer flags operations that use features requiring special handling, such as MTOM/XOP, MIME multipart, SOAP-encoded usage, or WS-Addressing.

After import, it is critical to review and confirm the inferred backend settings in the Configure the backend step.

Generated Payloads and Previews

For each operation, the import process generates two key artifacts to help you validate the SOAP-to-REST transformation:

• Sample REST request/response: Example JSON payloads for the generated REST endpoint.
• Generated SOAP request/response: A preview of the SOAP envelope that the platform will construct and send to the backend SOAP service, based on the incoming REST request.

These samples allow you to see the exact data transformation before publishing. The SOAP request can be copied directly into the SOAP application test tool for immediate validation. If the service has existing traffic, the platform may use learned values from production to create more realistic examples.

Change Detection on Re-import

When you import a WSDL that has been imported before (matched first by source name, then by target namespace), the platform performs a comparison against the most recent version of that artifact. The re-import comparison summary highlights:

• Added operations
• Removed operations
• Changed operations (with per-operation contract deltas)
• A count of breaking changes

This same mechanism powers the WSDL drift watch for live, published services. A service's WSDL compliance status is tracked as UP_TO_DATE, DRIFT_DETECTED, BREAKING_DRIFT, or UNTRACKED. If drift is detected, you can use the newer WSDL to generate a replacement draft that preserves your existing REST paths and runtime policies for any unchanged operations.

See Also

• Configure the backend
• Zero-touch autopilot
• How mapping works
• SOAP & XSD support
• Publish & version a service
• Learned examples

---

All SOAP-to-REST docs