WSDL Service and Draft Generation

Overview

The WsdlGenerationRepository is a data-access component responsible for translating an imported WSDL artifact into a functional API service configuration within the platform. It automates the creation of services, operations, and REST-to-SOAP mappings, effectively bootstrapping a REST-ful facade for a SOAP-based web service.

This component serves two primary purposes:

1. New Service Generation: Creates an entirely new API service from a specified WSDL artifact. This includes defining the service, creating a new service version, generating RESTful operations from the WSDL's SOAP operations, and optionally configuring a backend profile if the WSDL provides a service endpoint hint.
2. Replacement Draft Generation: Creates a new, inactive "draft" version for an existing service. This draft is based on a newer, comparable WSDL artifact, allowing API publishers to review and deploy updates to a service's contract without disrupting the active version.

It is an internal component typically invoked by higher-level administrative services when an API publisher initiates service creation or updates from a WSDL file. Its inputs are the UUID of a WSDL artifact and service metadata; its outputs are new records in the platform's database and a summary result object.

How it works

The repository provides transactional methods for creating and updating service configurations based on WSDL content.

Generating a New Service

When a new service is generated from a WSDL artifact, the platform executes the following sequence of operations, orchestrated by the generateServiceFromArtifactInternal method.

flowchart TD
    subgraph "API Publisher"
        A[Provides WSDL Artifact ID <br/> and Service Details]
    end

    subgraph "Platform"
        B(WsdlGenerationRepository)
        C{Service Key Available?}
        D[Create `s2r_service` and `s2r_service_version` records]
        E[For each WSDL Operation...]
        F[Infer REST Route and Method]
        G[Create `s2r_operation` Record]
        H{Backend Suggestion in WSDL?}
        I[Create Default `s2r_backend_profile`]
        J[Return `GeneratedServiceResult`]
    end

    A --> B
    B --> C
    C -- Yes --> D
    C -- No --> K((Fail with Error))
    D --> E
    E --> F
    F --> G
    G --> E
    E -- All Operations Processed --> H
    H -- Yes --> I
    I --> J
    H -- No --> J

1. Input Validation: The provided direction parameter is validated to ensure it is one of PUBLISH, CONSUME, or GATEWAY.
2. Contract Validation: The system runs a non-blocking validation check (WsdlContractRoundTripValidator) on the WSDL operations. This process verifies that example values provided in the WSDL schema conform to their own type constraints. Any validation failures are collected as warnings and included in the final result, but they do not stop the service generation process.
3. Service Key Availability: The system checks if the requested serviceKey is already in use within the specified environment. If it is, the process fails. The system also accounts for a legacy mode where service keys must be unique across all environments.
4. Service Creation: A new record is inserted into the s2r_service table with a status of draft. The direction determines whether the service is for publishing a backend (WSDL describes the backend) or consuming a service (WSDL describes the surface exposed to clients).
5. Version Creation: A corresponding version 1 record is inserted into s2r_service_version, linking the service to the source wsdl_artifact_id.
6. Operation Generation: The system iterates through each operation defined in the WSDL artifact:
   • An operationKey is generated from the SOAP operation name.
   • A REST-ful route (HTTP method and path) is inferred using WsdlRestRouteHeuristics. The system ensures generated routes are unique within the service.
   • A new record is inserted into the s2r_operation table. This record stores the operationKey, SOAP operation name, REST route, and JSON schemas for the request and response. It also copies the binding_style and a combined list of SOAP headers and headerFaults from the WSDL artifact into the operation_headers column.
   • Default request/response mappings are created via the OperationMappingRepository.
7. Backend Auto-Configuration: If the WSDL artifact includes a WsdlBackendSuggestionRecord (a hint about the SOAP service's location), a default s2r_backend_profile is created. This profile is configured with auth_type='none' and mtls_enabled=false; the API publisher must configure credentials separately.
8. Result: The process concludes by returning a GeneratedServiceResult object containing the UUIDs of the created service and version, along with any contract validation warnings.

Generating a Replacement Draft

When creating a replacement draft for an existing service, the generateReplacementDraftFromLatestComparable method is used. This allows for an in-place upgrade of a service's contract.

1. Prerequisite Check: The system first verifies that the target service does not already have an open draft version.
2. Artifact Discovery: It identifies the WSDL artifact associated with the specified source service version. It then searches for the latest "comparable" WSDL artifact that is newer than the current one. A comparable artifact is one with the same sourceName and targetNamespace. If no newer comparable artifact is found, the process fails.
3. Planning: The WsdlReplacementDraftPlanner is invoked to create a ReplacementPlan. This plan compares the operations from the existing service version with those in the new WSDL artifact. It categorizes each operation as preserved, new, or removed, and preserves configuration (e.g., timeouts, retries, enabled status) for existing operations.
4. Contract Validation: As with new service generation, the operations from the new WSDL are subjected to non-blocking contract validation.
5. Draft Version Creation: A new s2r_service_version record is created with an incremented version_no and a status of draft. It is linked to the new WSDL artifact ID.
6. Operation Persistence: The system iterates through the PlannedOperationShapes from the replacement plan and inserts corresponding records into the s2r_operation table for the new draft version.
7. Backend Configuration: If the original service had no backend profiles, the system attempts to create one based on backend suggestions in the new WSDL artifact.
8. Result: The process returns a WsdlReplacementDraftResult object, which summarizes the changes, including counts of preserved, new, and removed operations.

API Reference

The component exposes several public Java methods for managing WSDL-based service generation.

generateServiceFromArtifact

Creates a new service from a WSDL artifact with a specified service key.

Returns: GeneratedServiceResult

generateServiceFromArtifactAuto

Creates a new service from a WSDL artifact, automatically generating a unique service key. The key is derived from baseServiceKey by appending a numerical suffix (e.g., -2, -3) if the base key is already taken.

Returns: GeneratedServiceResult

generateReplacementDraftFromLatestComparable

Creates a new draft version for an existing service, based on the latest available comparable WSDL artifact.

Returns: WsdlReplacementDraftResult

findWsdlArtifactIdForVersion

A utility method to retrieve the WSDL artifact ID associated with a specific service version.

Returns: List<UUID>. Returns an empty list if the service version does not exist or if the wsdl_artifact_id column is not present in the database schema. Returns a list containing a single null element if the version exists but is not linked to a WSDL artifact.

Result Objects

GeneratedServiceResult

The result of creating a new service.

WsdlReplacementDraftResult

The result of creating a replacement draft.

Configuration

The generation process uses system-wide settings for default operation timeouts and retries. These can be configured via the SystemSettingRepository.

Example Operation Creation

The following SQL statement illustrates the data persisted into the s2r_operation table for each new operation generated from a WSDL. This demonstrates how WSDL metadata is mapped to the platform's operation model.

insert into s2r_operation (
    id, service_version_id, operation_key, soap_operation_name, rest_method, rest_path,
    soap_action, request_schema, response_schema, fault_schema, binding_style, operation_headers,
    enabled, timeout_ms, retry_count, debug_enabled,
    created_at, updated_at, created_by, updated_by
)
values (?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?::jsonb, '{}'::jsonb, ?, ?::jsonb, true, ?, ?, false, ?, ?, ?, ?)

Field Mapping:

• soap_operation_name: The name attribute from the WSDL operation.
• rest_method, rest_path: Inferred by WsdlRestRouteHeuristics.
• request_schema, response_schema: The JSON Schema representation of the WSDL message parts.
• binding_style: The style from the WSDL binding (e.g., document, rpc).
• operation_headers: A JSONB array containing the union of soap:header and soap:headerfault definitions applicable to the operation.
• timeout_ms, retry_count: Set to the system defaults during initial generation.

Troubleshooting

API publishers may encounter the following errors during service generation.

See Also

• WsdlImportRepository
• OperationMappingRepository
• SystemSettingRepository
• WsdlReplacementDraftPlanner
• WsdlContractRoundTripValidator
• WsdlRestRouteHeuristics

All SOAP-to-REST docs