WSDL Import API Reference

Overview

The WSDL Import API provides a set of administrative endpoints for importing Web Services Definition Language (WSDL) documents into the platform. It is the primary mechanism for onboarding existing SOAP-based services.

API publishers can import WSDLs from various sources: direct file upload, a re<customer>e URL, or raw XML content. Upon a successful import, the platform creates a persistent WSDL artifact, identified by a unique artifactId. This artifact serves as the foundation for subsequent actions, such as:

• Generating a draft service configuration: Creates a new service version pre-populated with operations and other details parsed from the WSDL.
• Automated "Autopilot" onboarding: A zero-touch process that imports a WSDL and immediately attempts to generate and configure a complete service draft.
• Repairing common WSDL issues: Provides tools to diagnose and fix problems like missing namespace prefixes or broken external schema references.
• Serving the contract: Allows downloading the original WSDL associated with a service version, which is useful for API consumers who need the contract for a SOAP client.

A key function of the import process is the resolution and persistence of the WSDL's complete schema closure. The system transitively fetches all referenced WSDLs and XML Schema Definitions (XSDs) at import time. This ensures that runtime validation can be performed without making external network calls, which enhances security and reliability.

How it works

The WSDL import process follows a consistent sequence of steps, regardless of the source. The primary goal is to parse the WSDL, store it as an immutable artifact, and prepare it for service generation.

flowchart TD
    subgraph "API Publisher"
        A[Sends WSDL via file, URL, or XML]
    end

    subgraph "API Platform"
        B[1. Receive request at Import Endpoint] --> C{Source Type?}
        C -- File Upload --> D[Read file bytes]
        C -- URL --> E[Fetch from URL]
        E --> F[SSRF Egress Guard]
        F --> G[Follow Redirects Manually]
        G --> H[Read response bytes]
        C -- Raw XML --> I[Read request body]

        D --> J[2. Parse WSDL Document]
        H --> J
        I --> J

        J --> K[3. Persist WSDL Artifact]
        K --> L[4. Resolve Schema Closure]
        L --> M[Fetch all wsdl:import, xsd:import, xsd:include]
        M --> N[5. Persist Schema Documents]
        K --> O[6. Create Audit Log]
        O --> P[7. Return Artifact ID and Preview]
    end

    A --> B
    P --> Q[Receives Artifact ID]

    subgraph "API Publisher (Later)"
        Q --> R[Uses Artifact ID to generate service]
    end

1. An API publisher sends a request to an import endpoint, such as POST /admin/v1/wsdl/import. The WSDL content is provided as a multipart file, a URL within a JSON payload, or as raw XML text.
2. If the source is a URL, the platform fetches it using a secure HTTP client. This client has automatic redirects disabled. It follows redirects manually, and each hop is validated by an OperatorUrlGuard to prevent Server-Side Request Forgery (SSRF) vulnerabilities.
3. The raw WSDL XML is parsed by the WsdlParser. This process extracts key information, including the targetNamespace, a suggested backend service URL, and a list of defined SOAP operations.
4. A WsdlImportResult record is created and stored in the WsdlImportRepository. This record contains the parsed metadata, the original source information, a SHA-256 hash of the content, and the full WSDL XML payload. The system assigns a unique artifactId (UUID) to this record.
5. The WsdlSchemaClosureResolver then analyzes the imported WSDL to find all transitively referenced documents (via wsdl:import, xsd:import, and xsd:include). It attempts to fetch and store each of these documents.
6. An audit log is created, recording the actor who performed the import and the outcome.
7. The API responds with a JSON object containing a preview of the imported artifact, including its artifactId. This ID can then be used in subsequent API calls to generate a service or trigger autopilot onboarding.

Examples

Import a WSDL from a file

This example uploads a WSDL file to create a new WSDL artifact.

curl -X POST "https://<platform-host>/admin/v1/wsdl/import" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/your/service.wsdl"

A successful request returns an HTTP 200 OK status and a JSON body containing the import preview, which includes the generated artifactId.

Import a WSDL from a URL and generate a service

This example demonstrates a two-step process: first, import a WSDL from a public URL, and second, use the resulting artifactId to generate a new service draft.

Step 1: Import from URL

curl -X POST "https://<platform-host>/admin/v1/wsdl/import-url" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://example.com/service?wsdl"
  }'

The response will contain the artifactId. Assume it is a1b2c3d4-e5f6-7890-1234-567890abcdef.

Step 2: Generate Service

curl -X POST "https://<platform-host>/admin/v1/wsdl/import/a1b2c3d4-e5f6-7890-1234-567890abcdef/generate-service" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceKey": "my-new-service",
    "serviceName": "My New SOAP Service",
    "environment": "dev",
    "direction": "PUBLISH"
  }'

A successful request returns an HTTP 200 OK status and a JSON body with details of the generated service version, including its versionId.

API Reference

WSDL Import and Management

These endpoints handle the creation and retrieval of WSDL artifacts.

Import WSDL from file

POST /admin/v1/wsdl/import

Imports a WSDL provided as a multipart file upload.

• Request Content-Type: multipart/form-data
• Response Content-Type: application/json

Request Parts

Responses

• 200 OK: Successful import. The body contains an import preview object.
• 400 Bad Request: The file is empty (S2R-ADM-1400) or the WSDL is malformed (S2R-ADM-1401).
• 500 Internal Server Error: An unexpected error occurred (S2R-ADM-1500).

Import WSDL from URL

POST /admin/v1/wsdl/import-url

Imports a WSDL from a specified URL. The platform fetches the WSDL content from the URL.

• Request Content-Type: application/json
• Response Content-Type: application/json

Request Body

Responses

• 200 OK: Successful import. The body contains an import preview object.
• 400 Bad Request: The url is missing, invalid, or blocked (S2R-ADM-1402); the URL fetch failed (S2R-ADM-1403); the response from the URL was empty (S2R-ADM-1400); or the WSDL is malformed (S2R-ADM-1401).
• 500 Internal Server Error: An unexpected error occurred (S2R-ADM-1500).

Import WSDL from XML text

POST /admin/v1/wsdl/import-xml

Imports a WSDL provided as raw XML in the request body. This is useful for importing repaired or manually constructed WSDLs.

• Request Content-Type: application/json, text/plain
• Response Content-Type: application/json

Request Body

The body can be a JSON object or raw XML text.

Responses

• 200 OK: Successful import. The body contains an import preview object.
• 400 Bad Request: The XML content is missing (S2R-ADM-1402) or the WSDL is malformed (S2R-ADM-1401).
• 500 Internal Server Error: An unexpected error occurred (S2R-ADM-1500).

Get WSDL import artifact

GET /admin/v1/wsdl/import/{artifactId}

Retrieves the import preview details for a previously imported WSDL artifact.

• Response Content-Type: application/json

Path Parameters

Responses

• 200 OK: The body contains the import preview object.
• 404 Not Found: No WSDL artifact with the specified ID was found (S2R-ADM-1404).

Download inbound WSDL for a service version

GET /admin/v1/services/{serviceId}/versions/{versionId}/inbound-wsdl

Downloads the original WSDL file that was used to create a specific service version.

• Response Content-Type: application/wsdl+xml

Path Parameters

Responses

• 200 OK: The body contains the raw WSDL XML content.
• 404 Not Found: The service version was not found, is not linked to a WSDL artifact, or the WSDL payload was not stored for the artifact (for very old imports) (S2R-ADM-0404).

WSDL-driven Service Generation

These endpoints use existing WSDL artifacts to create or configure services.

Generate service from WSDL artifact

POST /admin/v1/wsdl/import/{artifactId}/generate-service

Creates a new draft service version from a WSDL artifact. If serviceKey is omitted, the system suggests one based on the WSDL content.

• Request Content-Type: application/json
• Response Content-Type: application/json

Path Parameters

Request Body

Responses

• 200 OK: Service draft created successfully. The body contains details of the generated service version.
• 400 Bad Request: The artifact was not found, the request was invalid (S2R-ADM-1403), the direction is unsupported (S2R-VAL-0403), or the WSDL failed contract validation (WsdlContractValidationException.CODE).
• 500 Internal Server Error: An unexpected error occurred during generation (S2R-ADM-1501).

Autopilot Onboarding

Autopilot endpoints provide a "zero-touch" workflow by combining import and service generation into a single call.

Autopilot from an imported WSDL

POST /admin/v1/wsdl/import/{artifactId}:autopilot

Triggers autopilot onboarding from an existing WSDL artifact.

• Request Content-Type: application/json
• Response Content-Type: application/json

Path Parameters

Request Body: Same as generate-service.

Responses

• 200 OK: Autopilot process completed. The body contains the results, including the generated service details.
• 400 Bad Request: Invalid request (S2R-ADM-1403), unsupported direction (S2R-VAL-0403), or contract validation failure (WsdlContractValidationException.CODE).
• 500 Internal Server Error: An unexpected autopilot failure occurred (S2R-ADM-1502).

Autopilot from an uploaded WSDL file

POST /admin/v1/wsdl/import:autopilot

Imports a WSDL from a file and immediately triggers autopilot onboarding.

• Request Content-Type: multipart/form-data
• Response Content-Type: application/json

Request Parts

Responses

• 200 OK: Autopilot process completed.
• 400 Bad Request: Empty file (S2R-ADM-1400), malformed WSDL (S2R-ADM-1401), invalid arguments (S2R-ADM-1403), or contract validation failure (WsdlContractValidationException.CODE).
• 500 Internal Server Error: An unexpected autopilot failure occurred (S2R-ADM-1502).

Autopilot from a WSDL URL

POST /admin/v1/wsdl/import-url:autopilot

Imports a WSDL from a URL and immediately triggers autopilot onboarding.

• Request Content-Type: application/json
• Response Content-Type: application/json

Request Body

Responses

• 200 OK: Autopilot process completed.
• 400 Bad Request: Invalid arguments (S2R-ADM-1402), malformed WSDL (S2R-ADM-1401), or contract validation failure (WsdlContractValidationException.CODE).
• 500 Internal Server Error: An unexpected autopilot failure occurred (S2R-ADM-1502).

Autopilot from WSDL XML text

POST /admin/v1/wsdl/import-xml:autopilot

Imports a WSDL from raw XML text and immediately triggers autopilot onboarding.

• Request Content-Type: application/json, text/plain
• Response Content-Type: application/json

Request Body

Responses

• 200 OK: Autopilot process completed.
• 400 Bad Request: Invalid arguments (S2R-ADM-1402), malformed WSDL (S2R-ADM-1401), or contract validation failure (WsdlContractValidationException.CODE).
• 500 Internal Server Error: An unexpected autopilot failure occurred (S2R-ADM-1502).

Batch Autopilot Operations

These endpoints support autopilot onboarding for multiple WSDLs in a single request.

Batch autopilot from WSDL URLs

POST /admin/v1/wsdl/import-urls:autopilot

Executes autopilot for a batch of WSDLs specified by URLs.

• Request Content-Type: application/json
• Response Content-Type: application/json

Request Body

Responses

• 200 OK: Batch process completed. The body contains a report of successes and failures.
• 400 Bad Request: Invalid request body (S2R-ADM-1402).
• 500 Internal Server Error: An unexpected batch failure occurred (S2R-ADM-1502).

Batch autopilot from uploaded WSDL files

POST /admin/v1/wsdl/import-files:autopilot

Executes autopilot for a batch of WSDLs provided as uploaded files.

• Request Content-Type: multipart/form-data
• Response Content-Type: application/json

Request Parts

Responses

• 200 OK: Batch process completed.
• 400 Bad Request: No files provided or a file is empty (S2R-ADM-1400).
• 500 Internal Server Error: An unexpected batch failure occurred (S2R-ADM-1502).

WSDL Repair and Analysis

These endpoints provide tools to diagnose and fix common issues in WSDL documents before import.

Preview namespace repair

POST /admin/v1/wsdl/namespace-repair-preview

Analyzes a WSDL for missing namespace declarations and returns a repaired XML version.

• Request Body: A JSON object containing wsdlXml or url, and an optional namespaceMappings object for manual overrides.
• Response: A JSON object with the repair analysis, including repairedXml.

Preview external references

POST /admin/v1/wsdl/external-reference-preview

Analyzes a WSDL for external references (wsdl:import, xsd:import, xsd:include) and reports on their resolution status.

• Request Body: A JSON object containing wsdlXml or url.
• Response: A JSON object with a list of all external references and their status (resolved or failed).

Generate repair report

POST /admin/v1/wsdl/repair-report

Generates a comprehensive JSON report combining namespace and external reference analysis.

• Request Body: A JSON object containing wsdlXml or url, and optional namespaceMappings.
• Response: A detailed JSON report.

Download repair package

POST /admin/v1/wsdl/repair-package

Generates and downloads a ZIP archive containing the repaired WSDL, all resolved external schemas, placeholder files for failed references, and a JSON manifest.

• Request Body: A JSON object containing wsdlXml or url, and optional namespaceMappings.
• Response: A application/zip file.

Direction Parameter

Several endpoints accept a direction parameter. This field specifies the role of the service being created.

• PUBLISH: (Default) The WSDL describes a backend SOAP service that the platform will expose as a new API.
• CONSUME: The WSDL describes a SOAP API that the platform will expose to clients, which is then backed by a REST service.
• GATEWAY: The WSDL describes a contract for a SOAP-to-SOAP broker service.

If the direction parameter is provided with an unsupported value, the API will respond with a 400 Bad Request and error code S2R-VAL-0403.

Troubleshooting

All SOAP-to-REST docs