Generating Services from WSDL Artifacts

Overview

The WSDL Generation repository provides the core logic for creating and updating services from previously imported Web Services Description Language (WSDL) artifacts. It automates the translation of a SOAP-based contract into a RESTful service definition within the platform.

This component solves two primary use cases:

1. New Service Onboarding: It generates a new service, including its REST/SOAP operations, from a WSDL artifact. This process infers RESTful routes, sets default operation policies, and can automatically configure a backend profile if the WSDL artifact contains a service endpoint suggestion.
2. Service Updates: It creates a "replacement draft" for an existing service. This draft is a new, inactive service version based on a newer, comparable WSDL artifact. This allows API publishers to review and test changes before activating an updated contract.

The process is initiated with the ID of a WSDL artifact and service metadata. It results in new records being created in the platform's database for the service, its version, and its operations (s2r_service, s2r_service_version, s2r_operation). The output is a summary record containing the IDs of the created entities and any validation warnings.

Creating a New Service from a WSDL Artifact

When you generate a new service from a WSDL artifact, the system performs a series of steps to create all the necessary platform resources.

How it Works

The generation process is transactional and follows a well-defined sequence.

flowchart TD
    subgraph "API Publisher Inputs"
        A[WSDL Artifact ID]
        B[Service Metadata <br/>(Key, Name, Environment)]
    end

    subgraph "Service Generation"
        C[1. Start Generation]
        D{2. Service Key Available?}
        E[3. Validate WSDL Artifact]
        F[4. Run Contract Validation <br/>(generates non-blocking warnings)]
        G[5. Create Service & Version Shells]
        H[6. Generate Operations & REST Routes]
        I{7. Backend Suggestion in WSDL?}
        J[8. Create Default Backend Profile]
    end

    subgraph "Result"
        K[Success: New Service Created]
        L[Failure: Exception Thrown]
    end

    A --> C
    B --> C
    C --> D
    D -- Yes --> E
    D -- No --> L
    E --> F
    F --> G
    G --> H
    H --> I
    I -- Yes --> J
    J --> K
    I -- No --> K

1. Input Validation: The system first validates the inputs. It ensures the serviceKey is not already in use within the specified environment for your tenant. It also checks that the direction parameter is one of PUBLISH, CONSUME, or GATEWAY. If no direction is provided, it defaults to PUBLISH.
2. WSDL Operation Loading: It fetches all operations defined in the specified WSDL artifact. If the artifact contains no operations, the process fails.
3. Contract Validation: The system runs a "round-trip" validation on the schemas of all WSDL operations. This check verifies that any example values defined in the schema conform to the schema's own constraints (e.g., data type, pattern).

   WARNING

   Non-Blocking Validation: If validation failures are found, the service generation process does not stop. Instead, the failures are logged as warnings (with code S2R-ADM-0612) and returned in the contractWarnings field of the GeneratedServiceResult. This allows you to create the service and address the contract issues later.

4. Service and Version Creation: A new service record is inserted into s2r_service with a status of draft. A corresponding initial version record (version 1) is inserted into s2r_service_version, linking the service to the source wsdl_artifact_id.
5. Operation and Route Generation: The system iterates over each operation from the WSDL artifact:
   • Operation Key: A unique operation_key is generated from the SOAP operation name. If names conflict, a numeric suffix is added (e.g., my-op, my-op-2).
   • REST Route Inference: The WsdlRestRouteHeuristics component infers a unique REST method and path for the operation, avoiding conflicts with other operations in the same service.
   • Database Insertion: A new record is inserted into the s2r_operation table. This record includes the inferred REST route, SOAP metadata (soap_operation_name, soap_action), and JSON schemas.
   • Header and Binding Metadata: The operation's binding_style and any soap:header or soap:headerfault definitions are copied from the WSDL artifact to the s2r_operation record.
   • Default Policies: The operation is created with enabled=true, debug_enabled=false, and default values for timeout_ms and retry_count derived from system settings.
6. Backend Auto-Configuration: If the WSDL artifact includes a backend endpoint suggestion (WsdlBackendSuggestionRecord), the system automatically creates a default backend profile.
   • A new record is inserted into s2r_backend_profile named default.
   • The endpoint_url, soap_namespace, and soap_version are set from the suggestion.
   • Authentication is always initialized to auth_type='none' and mtls_enabled=false. You must configure credentials manually after creation.
   • This new profile is set as the default_backend_profile_id for the service.

API Reference

Service generation is invoked via internal Java methods.

generateServiceFromArtifact

Creates a new service with a specific serviceKey.

Returns: GeneratedServiceResult

generateServiceFromArtifactAuto

Creates a new service, automatically determining an available serviceKey. If the baseServiceKey is taken, it appends a numeric suffix (e.g., -2, -3) until an available key is found.

Returns: GeneratedServiceResult

Return Value: GeneratedServiceResult

This object contains details about the newly created service.

Creating a Replacement Draft from a WSDL Artifact

This feature allows you to update an existing WSDL-based service by creating a new draft version from a more recent WSDL artifact.

How it Works

The process identifies changes between the current service version and a new WSDL, creating a new draft that preserves existing configurations where possible.

flowchart TD
    subgraph "API Publisher Inputs"
        A[Existing Service ID]
        B[Source Version ID]
    end

    subgraph "Replacement Draft Generation"
        C[1. Start Draft Generation]
        D{2. Draft Already Exists?}
        E[3. Find Newer Comparable WSDL Artifact]
        F[4. Plan Changes <br/>(Preserved, New, Removed Ops)]
        G[5. Run Contract Validation on New WSDL <br/>(generates non-blocking warnings)]
        H[6. Create New Draft Service Version]
        I[7. Create Operations from Plan]
        J{8. Service has no Backend Profile?}
        K[9. Create Default Backend Profile]
    end

    subgraph "Result"
        L[Success: New Draft Version Created]
        M[Failure: Exception Thrown]
    end

    A --> C
    B --> C
    C --> D
    D -- Yes --> M
    D -- No --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J -- Yes --> K
    K --> L
    J -- No --> L

1. Context Loading and Validation: The system loads the context of the specified sourceVersionId and verifies that no other draft version already exists for the service. It also confirms the source version is linked to a WSDL artifact.
2. Artifact Discovery: It finds the WSDL artifact associated with the sourceVersionId and then searches for the latest "comparable" WSDL artifact that is newer. A comparable artifact has the same sourceName and targetNamespace. If no newer comparable artifact is found, the process fails.
3. Replacement Planning: The WsdlReplacementDraftPlanner is invoked. It compares the operations in the source version with those in the new WSDL artifact. It produces a plan that categorizes operations as preserved, new, or removed, and carries over settings (REST route, timeout, etc.) for preserved operations.
4. Contract Validation: As with new service generation, the system runs non-blocking contract validation on the operations from the new WSDL artifact. Any findings are returned as warnings.
5. Draft Version Creation: A new s2r_service_version record is created with status='draft' and is_active=false. It is assigned the next available version number for the service (e.g., 2, 3, etc.) and linked to the new WSDL artifact ID.
6. Operation Generation: The system creates new s2r_operation records for the new draft version based on the replacement plan. Settings for preserved operations are copied from the previous version, while new operations get default settings.
7. Backend Auto-Configuration: This step is conditional. A default backend profile is only created if the service does not have any existing backend profiles. If one or more profiles already exist, this step is skipped.

API Reference

generateReplacementDraftFromLatestComparable

Creates a new draft version for an existing service.

Returns: WsdlReplacementDraftResult

Return Value: WsdlReplacementDraftResult

This object summarizes the outcome of the draft creation.

Configuration

Operation generation relies on system-wide settings for default timeout and retry policies. These are configured in the SystemSettingRepository.

Troubleshooting

See Also

• WSDL Import: The process of uploading and cataloging WSDL files, which produces the artifacts used by this component.
• Replacement Draft Planning: The logic that compares two WSDL versions to determine which operations are preserved, added, or removed.
• Operation Data Mapping: After generation, each operation requires data mappings to be configured. Default mappings are created automatically.
• REST Route Heuristics: The component responsible for algorithmically generating unique and predictable REST endpoints from SOAP operation names.

All SOAP-to-REST docs