Quickstart: Publish a REST Facade for a SOAP Service

Overview

This quickstart provides the fastest path to creating and publishing a REST API facade for an existing SOAP backend service. By following these steps, you will deploy the platform's standalone Docker Compose stack on a single host, use the admin UI to import a WSDL file, configure the connection to your SOAP backend, review the automatically generated OpenAPI v3 specification, and publish a live, versioned service.

This guide focuses on the Publish direction, where the platform exposes a REST interface that proxies requests to a SOAP backend. It is intended for initial evaluation and development on a single host. For production deployments, refer to the installation guides for Kubernetes, OpenShift, or cloud-native platforms.

The process begins by running a local Docker Compose stack. You then interact with the admin UI to perform the onboarding, which involves parsing a WSDL, configuring backend details, and generating the corresponding REST API contract. Once published, the service is immediately available on the runtime component for testing.

Prerequisites

Before you begin, ensure your host environment meets the following requirements:

• Docker: Docker Engine version 24 or newer, with Docker Compose v2 installed. You can verify your version with docker compose version.
• System Resources: Approximately 2 GB of free RAM and 2 GB of free disk space for the Docker images and data volume.
• Network Access:
  • The host must have network connectivity to the target SOAP backend endpoint.
  • Outbound HTTPS access to the Specaria platform (portal.specaria.io) is required for licensing. The platform includes a 14-day offline grace period for transient network interruptions.
• SOAP Contract: A WSDL for the SOAP service, available as a local file, a reachable URL, or pasted XML content.

How it Works

The quickstart process guides you through a sequence of operations to stand up the platform and publish your first API. The platform components work together to ingest a SOAP definition, generate a REST equivalent, and serve traffic.

The flow is as follows:

1. You deploy a local stack consisting of the admin-ui, admin-api, runtime, worker, and a PostgreSQL database using Docker Compose.
2. Using the admin-ui, you import a WSDL. The admin-api parses it, infers RESTful paths and methods, and generates sample payloads.
3. You configure the backend endpoint URL and credentials for the SOAP service. These are stored securely.
4. The platform generates a complete OpenAPI v3 specification and a full-field mapping from REST to SOAP.
5. After reviewing the generated contract and confirming backend connectivity, you publish the service. This creates an immutable, versioned snapshot.
6. The runtime component immediately begins serving traffic for the new REST API, proxying requests to the configured SOAP backend.

flowchart TD
    subgraph "Local Host"
        A[API Consumer]
        B[Deploy Stack <br/>(Docker Compose)]
        C[Configure .env]
        D[Admin UI <br/>(http://localhost:8080)]
        E[Runtime]
    end

    subgraph "Platform Services"
        D -- "Import WSDL" --> F{Onboard Service}
        F -- "Set Backend URL & Auth" --> G{Configure Backend}
        G -- "Review Mappings" --> H{Generate OpenAPI v3}
        H -- "Publish v1" --> I{Publish Service}
    end

    J[SOAP Backend]

    A -- "1. REST API Call" --> E
    B --> C
    C --> E
    C --> D
    I -- "Activates on" --> E
    E -- "2. Proxies SOAP Call" --> J
    J -- "3. SOAP Response" --> E
    E -- "4. JSON Response" --> A

    style A fill:#d4edda,stroke:#155724
    style J fill:#f8d7da,stroke:#721c24

Step 1: Bring Up the Stack

First, download the s2r deployment bundle from the Specaria portal (portal.specaria.io). This bundle is self-contained and includes the docker-compose.standalone.yml file, an example environment file, and all necessary product images as tar archives. No source code compilation is required.

After downloading and unpacking the bundle, navigate into the created directory.

1. Load Docker Images Run the appropriate script to load the bundled product images into your local Docker daemon. This step only needs to be performed once.

   # For Linux or macOS
   ./scripts/load-images.sh
   
   # For Windows PowerShell
   # .\scripts\Load-Images.ps1
   

2. Configure Environment Secrets Copy the example environment file to create your local configuration.

   cp docker-compose.env.example .env
   

   Next, edit the .env file and provide values for the two required secrets. You can use openssl to generate secure random values.

   S2R_DB_PASSWORD=<value-from: openssl rand -base64 24>
   S2R_CREDENTIAL_KEY=<value-from: openssl rand -base64 32>   # 32-byte AES key
   

3. Start the Services Use Docker Compose to start the full stack in detached mode. The command points to the standalone configuration file, which exposes the admin UI on a plain HTTP port.

   docker compose -f docker-compose.standalone.yml up -d
   

   The stack includes the following services: PostgreSQL, admin-api, runtime, worker, and admin-ui. The initial startup may take 30-60 seconds longer than subsequent starts as the database schema is initialized via Flyway migrations.

4. Verify Status Check that all containers are running and view the logs to monitor the boot process.

   # Check container status
   docker compose -f docker-compose.standalone.yml ps
   
   # Tail logs from the admin-api to see migrations and startup
   docker compose -f docker-compose.standalone.yml logs -f admin-api
   

   Once started, the admin UI will be available at http://<host>:8080. The default port 8080 is configured by the S2R_ADMIN_UI_HOST_PORT environment variable.

Step 2: Open the Admin UI

Navigate to http://<host>:8080/ in your web browser. For this quickstart, you can proceed without configuring single sign-on (SSO).

From the main Dashboard, navigate to WSDL Onboarding to begin.

Step 3: Import a WSDL

In the WSDL Onboarding section, you can import your SOAP contract via file upload, a URL, or by pasting the raw XML. The platform will parse the WSDL and present a review screen with:

• A suggested backend endpoint, SOAP version, and authentication hints.
• A suggested REST method and path for each SOAP operation (e.g., GET /customers/{id}), which you can edit.
• Generated sample request and response payloads for each operation.
• A "zero-touch readiness" summary, indicating the complexity and automation potential.

If the WSDL contains errors like missing namespace declarations, you can use the built-in namespace repair tool.

Step 4: Configure the Backend

Next, define the connection details for your SOAP backend. These settings are environment-scoped (e.g., dev, test, prod), allowing you to use different endpoints and credentials for each stage.

Configure the following for your dev environment:

• Endpoint URL: The address of your SOAP service (e.g., https://<soap-host>/services/<Service>).
• SOAP version: 1.1 or 1.2. This is often pre-filled based on the WSDL.
• Auth profile: Select or create an authentication profile with the necessary credentials. Credentials are encrypted at rest using the S2R_CREDENTIAL_KEY and are never exposed in logs or API responses.

Use the built-in connection / auth diagnostic tool to verify that the platform can reach the backend host and authenticate successfully before proceeding.

Step 5: Review the Generated OpenAPI v3

The platform generates a deterministic, full-field mapping from the WSDL and produces a standards-compliant OpenAPI v3 document. Before publishing, review the generated contract:

• The JSON schema reflects your configured conversion options, such as field casing, null handling, and error shapes.
• Each operation is assessed for its auto-mapping readiness, helping you identify which parts are fully automated.
• Faults defined in the WSDL are translated into specific error schemas in the OpenAPI document.
• If a specific field requires a non-default mapping, you can apply a field-level override directly in the UI without writing any code.

Step 6: Publish and Version the Service

Once the publish-readiness checks are green (e.g., backend is reachable, mappings are complete), you can save and publish the service.

• Publishing creates an immutable version (e.g., v1) of the service configuration and mappings.
• To update the service, you re-import the WSDL, which creates a new draft version (v2) along with a detailed change report. You can then activate the new version or roll back to a previous one with a single click.

Save the service and set it active to make it live on the runtime.

Step 7: Make a Test Call

A published service is immediately available on the runtime component. The URL path is structured to include the direction, environment, and service key.

API Endpoint Reference

Path Parameters:

• env: The environment key, such as dev.
• serviceKey: The unique key for the published service.
• operation-path: The RESTful path defined for the operation, including any path parameters (e.g., customers/12345).

Example Request: To call a GetCustomer operation (published as GET /customers/{id}) in the dev environment for a service with the key <serviceKey>:

curl -sS \
  "http://<your-host>:8080/publish/dev/<serviceKey>/customers/12345" \
  -H "Accept: application/json"

The runtime receives this request, constructs a corresponding SOAP message, calls the configured backend, transforms the SOAP response back into JSON, and returns it to the client.

Step 8: Observe the Call in the UI

Navigate to the Observability section in the admin UI to monitor traffic and troubleshoot issues.

• Live Traffic Log: View detailed request/response payloads and headers for individual calls.
• Searchable Logs: Trace requests using the correlation ID that is attached to every call. Logs can be filtered by environment, service, operation, and result code.
• Dashboards: Analyze performance and traffic trends with dashboards that query pre-computed aggregation tables for fast responses.

Troubleshooting

The platform provides specific error codes for common failure scenarios.

Other notable behaviors:

• Timeouts: The default per-operation timeout is 100 ms.
• Retries: The default number of retries for a failed backend call is 2.
• Both timeouts and retries are configurable per operation.

Next Steps

With your first service running, you can explore more advanced features:

• Automate Onboarding: Use Discovery & connectors to automatically populate your service inventory from live traffic instead of manual WSDL imports.
• Customize Mappings: Fine-tune the REST-to-SOAP transformation with platform-wide, per-service, or per-field Conversion options.
• Deploy to Production: Follow the Installation guides for production environments like GCP, Kubernetes, or OpenShift.
• Get Help: Visit the Support page for assistance.

See Also

• Core Concepts
• System Requirements
• Installation Guide
• Docker Compose Installation
• Onboarding: Consume Direction
• Onboarding: Zero-touch Autopilot
• Onboarding: Generate & Review OpenAPI
• Onboarding: Publish & Version a Service
• Conversion Options
• Field-level Overrides
• Security: Authentication
• Security: RBAC & Roles
• Security: Backend Credential Encryption
• Licensing: Egress Allow-list
• Observability
• Discovery & Connectors
• API Reference: Error Codes
• Support

All SOAP-to-REST docs