Quickstart: Publish a REST API from a WSDL using Docker Compose

Overview

This guide provides the fastest path to publish a REST API facade over an existing SOAP backend service. You will deploy the standalone Docker Compose stack on a single host, use the admin UI to import a WSDL contract, configure the backend connection, generate and review an OpenAPI v3 specification, and publish the new service.

The standalone Docker Compose stack is a supported deployment target for single-host installations and evaluations. It includes all necessary components to run the platform: a PostgreSQL database, the admin API, the runtime gateway, a background worker, and the admin web UI.

This quickstart focuses on the Publish direction, where the platform exposes a REST interface that proxies requests to a SOAP backend. The platform also supports the Consume direction (SOAP facade over a REST backend).

Before proceeding, it is recommended to review the Core concepts to understand terms like service, operation, mapping version, and direction.

Prerequisites

To complete this quickstart, you will need the following:

• A host with Docker Engine 24+ and Docker Compose v2 or later.
• Approximately 2 GB of free RAM and 2 GB of free disk space for Docker images and the data volume.
• Network connectivity from the host to your target SOAP backend endpoint.
• A WSDL contract for the SOAP service, available as a file, a URL, or pasted XML content.
• Outbound HTTPS connectivity to the Specaria platform for licensing. The platform includes a 14-day offline grace period for transient network interruptions.

All values shown in <angle-brackets> are placeholders and must be replaced with your specific values.

Step 1: Bring up the Stack

First, obtain the deployment configuration and set up the required secrets.

1. Clone the repository:

   git clone <repo-url> soap-to-rest && cd soap-to-rest
   

2. Configure secrets: Copy the example environment file to create your local configuration.

   cp docker-compose.env.example .env
   

   Edit the new .env file and provide values for the two required variables. You can use openssl to generate secure random values.

   # .env
   S2R_DB_PASSWORD=<value-from: openssl rand -base64 24>
   S2R_CREDENTIAL_KEY=<value-from: openssl rand -base64 32>
   

   The S2R_CREDENTIAL_KEY is a 32-byte AES key used to encrypt backend credentials at rest in the database. This key must be kept stable; regenerating it will invalidate all previously saved credentials. If this key is not set, the services will fail to start and log error S2R-ADM-0419 or S2R-RUN-0419.

3. Start the services: For a single-host evaluation, use the docker-compose.standalone.yml file. This file exposes the admin UI on a plain HTTP port, intended to be placed behind a TLS-terminating reverse proxy or load balancer.

   # Build the container images
   docker compose -f docker-compose.standalone.yml build
   
   # Start the services in detached mode
   docker compose -f docker-compose.standalone.yml up -d
   

   The stack consists of 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 admin-api service runs Flyway database migrations on its first launch.

4. Verify the status: Check that all containers are running and view the logs to monitor the startup process.

   # Check container status
   docker compose -f docker-compose.standalone.yml ps
   
   # Tail the logs of the admin API to watch for migrations and boot completion
   docker compose -f docker-compose.standalone.yml logs -f admin-api
   

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

Step 2: Open the Admin UI

Navigate to http://<host>:8080/ (or the address of your reverse proxy) in a web browser. You will land on the Dashboard. For this guide, proceed to the WSDL Onboarding section.

For production deployments, it is critical to secure the admin UI with an identity provider (e.g., IAP, Azure AD, SAML, OIDC) and configure Role-Based Access Control (RBAC).

Step 3: Import a WSDL

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

• Inferred details such as the backend endpoint URL, 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 based on WSDL features like choices, wildcards, and polymorphism.

If the WSDL contains errors like missing namespace declarations, you can use the namespace repair feature. When re-importing an updated WSDL for an existing service, the platform generates a change report detailing added, removed, and modified operations.

For large WSDLs, the zero-touch autopilot feature can generate a draft service, operations, and mappings in a single step, providing a readiness score for each operation.

Step 4: Configure the Backend

Define the connection details for the target SOAP backend. These settings are environment-scoped (e.g., dev, test, prod), allowing you to promote the same service definition across different environments with distinct backend configurations.

• 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 imported WSDL.
• Auth profile: The credentials required to access the backend service. Credentials are encrypted at rest using the S2R_CREDENTIAL_KEY and are never logged or exposed in plaintext.

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

Step 5: Review the Generated OpenAPI v3

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

• The JSON schema reflects the configured conversion options, such as field casing, null handling, and fault shapes.
• Each operation is assessed for its auto-mapping readiness (auto-ready, auto-ready-with-warnings, or manual-required).
• Faults declared in the WSDL are translated into per-operation fault schemas in the OpenAPI specification.
• If a specific field requires a different mapping than the generated default, 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 met (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 (e.g., v2). The platform provides a change report comparing the new version to the old one. You can activate the new version when ready or roll back to a previous version with a single click.

Step 7: Make a Test Call

Published services in the "Publish" direction are accessible on the runtime via a structured path that includes the direction and environment.

Endpoint Format

The general format for a runtime API call is:

<METHOD> /publish/<env>/<serviceKey>/<operation-path>

• <METHOD>: The HTTP method (e.g., GET, POST) configured for the operation.
• publish: The direction segment, required for all Publish-direction services.
• <env>: The environment key (e.g., dev).
• <serviceKey>: The unique key for the service.
• <operation-path>: The RESTful path defined for the operation.

Example Request

For an operation GetCustomer published as GET /customers/{id} in the dev environment, a test call would look like this:

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

The runtime receives this REST request, converts it to a SOAP message, invokes the backend SOAP service, and transforms the SOAP response back into a JSON payload according to your configured mappings.

You can also use the in-app test harness to invoke operations directly from the admin UI during the onboarding process.

Step 8: Observe Traffic

After making a test call, use the Observability section in the admin UI to monitor traffic and diagnose behavior.

• Live Traffic Log: Shows request/response payloads and headers for individual calls.
• Searchable Runtime Logs: Allows you to find logs using filters like correlation ID, result code, environment, service, and operation.
• Dashboards: Provide sub-second performance metrics and rollups derived from pre-computed aggregation tables.

Configuration Reference

The following environment variables are used to configure the standalone Docker Compose stack. They should be set in the .env file.

Name	Required	Default	Description
S2R_DB_PASSWORD	Yes	—	The password for the internal PostgreSQL database user.
S2R_CREDENTIAL_KEY	Yes	—	A 32-byte AES key, provided as a base64-encoded string, for encrypting backend credentials. Must be kept stable.

The source also specifies the default admin UI port:

• S2R_ADMIN_UI_HOST_PORT: The host port for the admin UI. Defaults to 8080.

Troubleshooting

• Slow Initial Startup: The first time the stack starts, the admin-api service runs database migrations, which can add 30-60 seconds to the boot time.
• Service Fails to Start: If the S2R_CREDENTIAL_KEY environment variable is not set, the admin-api and runtime services will refuse to start, logging error S2R-ADM-0419 or S2R-RUN-0419.
• HTTP 400 Bad Request: If a request to the runtime API omits the direction segment (e.g., /publish/), the gateway will return an HTTP 400 error with code S2R-RUN-0405.
• HTTP 413 Payload Too Large: The runtime rejects synchronous request payloads larger than 30 MB with an HTTP 413 error and code S2R-RUN-0413.
• Connection Issues: Use the connection / auth diagnostic tool in the UI to test connectivity and authentication to the backend SOAP service from the platform host.
• WSDL Parsing Errors: If your WSDL has issues like missing namespaces, use the namespace repair feature during import.

Next Steps

• Automate Service Discovery: Instead of manually importing WSDLs, configure Discovery & connectors to populate your service inventory from live traffic.
• Tune Mappings: Customize the REST-to-SOAP transformation using platform-wide, per-service, or per-field Conversion options.
• Move to Production: See the Installation guide for deploying on GCP or Kubernetes/OpenShift with Helm.
• Get Help: Refer to the Support guide.

See Also

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

---

All SOAP-to-REST docs