WSDL Artifact Persistence and Management

Overview

The WSDL Import Repository is a data access component responsible for the persistence and management of WSDL artifacts within the platform's database. When an API publisher imports a WSDL file or provides a URL, this repository handles the creation, retrieval, and updating of records that represent the WSDL and its parsed contents.

Its primary function is to store structured data extracted from WSDL files, including:

• Artifact Metadata: The source of the WSDL (e.g., filename or URL), its checksum, and its target namespace.
• SOAP Operations: Detailed records for each operation defined in the WSDL, including message formats, SOAP actions, and associated XML schemas.
• Raw WSDL Content: The full XML text of the imported WSDL.
• Service Version Linkage: Associations between a WSDL artifact and the specific service versions that use it.

This component sits between high-level API management services and the database, providing a durable, queryable store for all imported WSDLs. All database operations are automatically scoped to the active tenant, ensuring strict data isolation in a multi-customer environment.

How it Works

The repository manages WSDL data primarily across two database tables: s2r_wsdl_artifact for the top-level artifact metadata and s2r_wsdl_operation_catalog for the individual SOAP operations within each artifact.

flowchart TD
    A[API Publisher] -- "Imports WSDL (upload or URL)" --> B[API Platform];
    B -- "1. Parses WSDL" --> C{WSDL Metadata & Operations};
    B -- "2. Persists via Repository" --> D{Persistence Layer};
    subgraph "Stored Artifact"
        D -- creates --> E[WSDL Artifact Record];
        D -- creates --> F[WSDL Operation Records];
    end
    E -- "has many" --> F;

Artifact Creation

When a new WSDL is imported, the create method orchestrates the persistence process:

1. A unique UUID is generated for the new artifact (artifact_id).
2. The provided sourceName (e.g., a filename or URL) is normalized. If it exceeds 300 characters, it is truncated and appended with a short SHA-256 hash of the original string to maintain uniqueness while respecting database column limits.
3. A new record is inserted into the s2r_wsdl_artifact table. This record includes metadata like source_type, the normalized source_name, checksum_sha256, target_namespace, and the user who imported it. The raw wsdl_xml is also stored if provided.
4. If the source_type is url, the source_url column is populated with the normalized source name. This URL is used by maintenance processes to re-fetch the WSDL if needed.
5. The repository then iterates through the list of WsdlOperationRecord objects provided. For each operation:
   • A new record is inserted into the s2r_wsdl_operation_catalog table, linked to the parent artifact_id.
   • Complex metadata, such as the request_schema, response_schema, operation_faults, and operation_headers, are serialized into their respective JSONB database columns.
   • SOAP headers (headers) and header faults (headerFaults) are combined into a single list before being serialized into the operation_headers column. A kind field within each header object distinguishes its type.
6. A WsdlImportResult object, containing the details of the newly created artifact and its operations, is returned to the caller.

Source Name Normalization

To prevent database errors from overly long source names (like complex URLs), the normalizeSourceName function truncates any name longer than MAX_SOURCE_NAME_LENGTH (300 characters).

The format for a truncated name is: [first N characters]...#[12-char-sha256-hash]

For example, a 400-character URL would be transformed into a 300-character string, with the end portion replaced by an ellipsis and a short hash of the original URL.

// Example of the normalization logic
String originalName = "https://example.com/very/long/path/that/exceeds/the/limit/" + "a".repeat(300);
String normalized = normalizeSourceName(originalName); 
// `normalized` will be a 300-character string ending in "...#" followed by a 12-character hash.

Data Retrieval and Maintenance

The repository provides several methods for retrieving and maintaining WSDL artifacts:

• Direct Lookup: findById and findWsdlXmlById retrieve a full artifact or just its raw XML content, respectively.
• Comparative Search: findLatestComparable and findLatestComparableNewer are used to find previously imported artifacts that are similar to a new one, based on matching source_name or target_namespace. This helps identify potential duplicates or updates.
• Data Rehydration: The findRehydrationCandidates method identifies service versions linked to artifacts that are missing their raw wsdl_xml content (a state common for artifacts imported before this feature was added). A separate "rehydrate" service uses this list to re-fetch the WSDLs from their original source_url.
• Backfill Linking: The findUnlinkedServiceVersions method finds service versions that are not linked to any WSDL artifact (wsdl_artifact_id is NULL). A "backfill" service uses this information to find a matching WSDL and create the association using linkArtifactToServiceVersion.

Schema-Aware Operations

To ensure backward compatibility with older platform installations, several methods dynamically check for the existence of specific database columns before executing a query. For instance, findRehydrationCandidates and findUnlinkedServiceVersions first call columnExists to verify that s2r_service_version.wsdl_artifact_id is present. If the column does not exist, the methods return an empty list, preventing SQL errors on legacy schemas.

API Reference

The WsdlImportRepository exposes the following public methods for managing WSDL artifacts.

create

Persists a new WSDL artifact and its associated operations to the database. Two overloads exist; the primary one accepts the full WSDL XML.

Parameters

Returns

A WsdlImportResult object containing the full details of the newly persisted artifact.

Other Public Methods

Data Structures

The repository uses several record types to model WSDL data.

WsdlImportResult

Represents a fully persisted WSDL artifact, including its operations.

WsdlOperationRecord

Represents a single parsed SOAP operation from a WSDL.

RehydrationCandidate

Contains the necessary information for a maintenance process to re-fetch a missing WSDL.

UnlinkedServiceVersionCandidate

Contains information for a maintenance process to find and link a WSDL to a service version.

Example SQL Query

The following SQL is used by the findById method to retrieve the main artifact record. Note the TENANT clause, which ensures multi-tenant data isolation.

select id, source_type, source_name, checksum_sha256, target_namespace, inferred_backend::text as inferred_backend, imported_at
from s2r_wsdl_artifact
where id = ?
  and tenant_id = current_setting('s2r.tenant')::uuid

Troubleshooting

• JSON Serialization Failures: Methods that serialize data to JSONB (e.g., create) will throw an IllegalStateException if an object cannot be converted to a JSON string. This is a fatal error for the import operation.
• JSON Deserialization Failures: Methods that parse JSON from the database (e.g., mapOperationRow) are designed to be resilient. If a JSONB column contains malformed or unparsable data, the method will return an empty List or Map instead of throwing an exception. This prevents read operations from failing but may hide underlying data corruption issues.
• Missing WSDL XML: Calling findWsdlXmlById for an artifact imported before database migration V82 will return an empty Optional, as the raw XML was not stored at that time. This is expected behavior.
• Concurrent Deletion: The linkArtifactToServiceVersion method may return 0 if the target service version is deleted by another process between the time it was selected for backfill and the time the UPDATE statement is executed.

All SOAP-to-REST docs