Generating API Services from WSDL Artifacts

# Generating API Services from WSDL Artifacts

## Overview

The `WsdlGenerationRepository` is a component of the Admin API that automates the creation of API services from previously imported WSDL artifacts. It bridges the gap between SOAP-based web services and the platform's REST-centric architecture by translating a WSDL contract into a corresponding API service definition, complete with RESTful operations and foundational configuration.

This component is primarily used during the API onboarding process. It is invoked when an API publisher wishes to:
1.  Create a new API service by importing a WSDL file.
2.  Create a new draft version of an existing service to reflect an updated WSDL.

The repository takes a WSDL artifact ID as its main input, along with metadata such as the desired service key and environment. It then orchestrates the creation of all necessary database records, including the service shell, a new service version, and a set of operations derived from the WSDL. The result is a 'draft' service that can be further configured and published.

## How it works

The generation process follows two primary paths: creating a new service from scratch or creating a replacement draft for an existing service.

### Generating a New Service

When a new service is generated from a WSDL artifact, the system performs a sequence of steps to create and configure all required components. This flow is initiated by calls to `generateServiceFromArtifact` or `generateServiceFromArtifactAuto`.

```mermaid
sequenceDiagram
    participant P as API Publisher
    participant A as Admin API
    participant W as WSDL Artifact Store
    participant D as Service Catalog (Database)

    P->>A: Request service generation (WSDL Artifact ID, Service Key, etc.)
    A->>W: Fetch WSDL operations for artifact
    W-->>A: Return operations
    A->>A: Validate contract (schemas vs. examples)
    A->>D: Check if Service Key is available
    D-->>A: Confirm availability
    A->>D: INSERT into s2r_service (status='draft')
    A->>D: INSERT into s2r_service_version
    loop For each WSDL operation
        A->>A: Infer REST route and operation key
        A->>D: INSERT into s2r_operation
    end
    alt WSDL suggests a backend
        A->>D: INSERT into s2r_backend_profile
        A->>D: UPDATE s2r_service (set default backend)
    end
    A-->>P: Return GeneratedServiceResult (IDs of new entities)

The process unfolds as follows:

1. Input Validation: The system first validates the direction parameter, which must be PUBLISH, CONSUME, or GATEWAY. It then fetches all WsdlOperationRecord entries associated with the provided artifactId. If no operations are found, the process fails.
2. Contract Validation: Before writing any data, the WsdlContractRoundTripValidator inspects the WSDL operations. It validates that any example values provided in the WSDL schemas conform to the constraints of their corresponding data types. This proactive check prevents the creation of services that would fail runtime validation.
3. Service Key Availability: The system checks if the requested serviceKey is already in use within the specified environment.
   • The generateServiceFromArtifact methods require the caller to provide a unique key.
   • The generateServiceFromArtifactAuto methods will automatically find the next available key by appending a numerical suffix (e.g., my-service-2, my-service-3) if the base key is taken.
   • In systems with legacy global uniqueness constraints, the key must be unique across all environments.
4. Service and Version Creation: A new record is inserted into the s2r_service table with a status of draft. A corresponding record is created in s2r_service_version to represent the first version of this service, linking it to the source artifactId.
5. Operation Generation: The system iterates over each operation from the WSDL artifact:
   • Key and Route Inference: WsdlRestRouteHeuristics generates a unique operation_key and infers a REST rest_method (e.g., POST) and rest_path for the operation, ensuring no route collisions within the service.
   • Database Insertion: A new record is inserted into the s2r_operation table. This record captures critical metadata from the WSDL, including the soap_operation_name, soap_action, request/response schemas, binding_style, and a JSON array of operation_headers (which combines both soap:header and soap:headerfault definitions).
   • Default Mappings: A default identity mapping is created for the operation via the OperationMappingRepository.
6. Backend Auto-Configuration: If the WSDL artifact contains a WsdlBackendSuggestionRecord, the system automatically creates a default backend profile in the s2r_backend_profile table using the suggested endpoint URL. This profile is created with auth_type set to none and requires manual configuration by an API publisher to add credentials.
7. Result: The process concludes by returning a GeneratedServiceResult object, which contains the UUIDs of the newly created service, version, and backend profile, along with a list of the generated operations.

Generating a Replacement Draft

When an API publisher needs to update a service with a newer WSDL, the generateReplacementDraftFromLatestComparable method is used. This process creates a new, inactive draft version without affecting the currently active service version.

1. Find Artifacts: The system identifies the WSDL artifact linked to the specified sourceVersionId and searches for the latest "comparable" WSDL artifact that has been imported more recently. A comparable artifact is one with the same sourceName and targetNamespace. If no newer comparable artifact exists, the operation fails.
2. Pre-condition Checks: The system verifies that the service does not already have an existing draft version.
3. Plan Replacement: The WsdlReplacementDraftPlanner is used to create a ReplacementPlan. It compares the operations in the existing service version with those in the new WSDL artifact. This plan determines which operations are preserved, which are new, and which are removed. For preserved operations, settings like enabled, timeout_ms, retry_count, and debug_enabled are carried forward.
4. Contract Validation: As with new service generation, the WsdlContractRoundTripValidator validates the operations from the new WSDL artifact.
5. Create New Version: 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. Apply Plan: The system iterates through the PlannedOperationShape list from the replacement plan and creates s2r_operation records for the new version accordingly.
7. Backend Configuration: If the service does not have any existing backend profiles, the system will attempt to auto-configure one based on the backend suggestion in the new WSDL artifact.
8. Result: The method returns a WsdlReplacementDraftResult, which summarizes the changes, including the count of preserved, new, and removed operations, and the ID of any auto-configured backend.

Component API

The WsdlGenerationRepository exposes several public methods for service generation.

generateServiceFromArtifact

Creates a new service and its first version from a WSDL artifact, using a caller-specified service key.

GeneratedServiceResult generateServiceFromArtifact(UUID artifactId, String serviceKey, String serviceName, String environment, String direction, String actor)

| Parameter | Type | Description - | artifactId | UUID | The unique identifier of the imported WSDL artifact. - | serviceKey | String | The unique key for the new service within the specified environment. Must not already exist. - | serviceName | String | A human-readable name for the service. - | environment | String | The target environment for the new service (e.g., "development", "production"). - | direction | String | The service direction. Must be PUBLISH, CONSUME, or GATEWAY. If null or blank, defaults to PUBLISH. - | actor | String | The identity of the user or system performing the action. Used for auditing. -

• Returns: A GeneratedServiceResult object containing details of the created service.
• Throws: IllegalArgumentException if the serviceKey already exists or other inputs are invalid. DataIntegrityViolationException may be thrown on a race condition for key creation.

generateServiceFromArtifactAuto

Creates a new service by automatically determining an available serviceKey. It takes a baseServiceKey and appends a suffix if the base key is already in use.

GeneratedServiceResult generateServiceFromArtifactAuto(UUID artifactId, String baseServiceKey, String serviceName, String environment, String direction, String actor)

| Parameter | Type | Description - | artifactId | UUID | The unique identifier of the imported WSDL artifact. - | baseServiceKey | String | The preferred service key. If unavailable, a numerical suffix will be added to find a unique key. - | serviceName | String | A human-readable name for the service. -

• Returns: A GeneratedServiceResult object containing details of the created service, including the resolvedServiceKey that was used.
• Throws: IllegalStateException if an automatic retry fails due to a legacy global service key constraint.

generateReplacementDraftFromLatestComparable

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

WsdlReplacementDraftResult generateReplacementDraftFromLatestComparable(UUID serviceId, UUID sourceVersionId, String actor)

| Parameter | Type | Description - | serviceId | UUID | The ID of the service to update. - | sourceVersionId | UUID | The ID of the existing service version that will be the basis for the update. - | actor | String | The identity of the user or system performing the action. -

• Returns: A WsdlReplacementDraftResult object summarizing the changes between the old and new versions.
• Throws: IllegalArgumentException if no newer comparable WSDL artifact is found, or if the source version is not linked to a WSDL. IllegalStateException if a draft version already exists for the service.

findWsdlArtifactIdForVersion

Retrieves the WSDL artifact ID associated with a specific service version.

List<UUID> findWsdlArtifactIdForVersion(UUID serviceId, UUID versionId)

• Returns: A List containing the UUID of the WSDL artifact. The list is empty if the wsdl_artifact_id column does not exist in the database schema. The list contains a single null element if the version exists but is not linked to an artifact.

Configuration

The generation process uses system-wide settings to configure default values for new operations. These can be configured in the SystemSettingRepository.

| Setting | Type | Default | Description - | default_timeout_ms | Integer | 1000 | The default backend request timeout in milliseconds for newly generated operations. The system enforces a range of 1 to 60000 ms; values outside this range will be ignored in favor of the fallback default.

---

All SOAP-to-REST docs