Onboard a SOAP Service as a REST API

Overview

This guide provides end-to-end instructions for an API publisher to onboard their first SOAP service onto the platform. After a new installation, the platform is empty; this process populates it with services.

The platform provides two primary methods for onboarding a SOAP service and exposing it as a REST API:

1. Auto-Discovery (Preferred): The platform analyzes access logs forwarded from an API gateway to automatically identify SOAP services, their operations, and their data schemas based on live traffic. This is the recommended path as it uses real-world usage data.
2. Manual WSDL Upload (Fallback): An API publisher provides a WSDL file for the SOAP service. The platform parses the WSDL to define the service, its operations, and schemas. This path is useful when gateway traffic is not yet available or for onboarding a service before it is exposed at the edge.

In both cases, the outcome is a new, fully-functional REST API endpoint, complete with an OpenAPI v3 specification, that acts as a facade for the underlying SOAP service. The original SOAP service and its traffic flow remain unaffected.

Prerequisites

Before you begin, ensure the following requirements are met:

• The platform installation is complete.
• You have credentials to log in to the administration portal at https://s2r.your-domain.com/.
• You have access to one of the following:
  • Gateway Syslog Source: An API gateway configured to forward its access logs to the platform's ingest endpoint.
  • WSDL File: A Web Services Definition Language (.wsdl) file for the target SOAP service, available either as a file or at a reachable URL.

Onboarding via Auto-Discovery

This method allows the platform to learn about your services from live traffic data forwarded from an API gateway.

How It Works

1. Your API gateway sends syslog messages containing access log records to the platform's ingest endpoint.
2. The platform's ingest service receives and parses these records. For generic gateways, it expects JSON-formatted records at https://s2r.your-domain.com/ingest/v1/generic/traffic.
3. The platform aggregates traffic data in 5-minute windows, inferring service boundaries, endpoint URLs, and SOAP operations from the traffic patterns (e.g., from URI segments or SOAPAction headers).
4. Discovered services appear in the Discovery view, ready for an API publisher to review and formally onboard.

Step-by-Step Instructions

1. Configure Gateway Logging: Configure your API gateway to forward its access-log syslog feed to the platform's ingest endpoint. Connection details are provided during installation and can be found in your operator portal under Onboarding → Gateway connector.
2. Wait for Discovery: Allow approximately 10 minutes for the platform to process at least one 5-minute aggregation window.
3. Navigate to Discovery: In the platform UI, select Discovery from the sidebar. You should see a list of discovered services with the following details:
   • Inferred service name
   • Endpoint URL
   • Traffic counters (24h / 7d / 1M)
   • Sample request and response payloads in the "Good Examples" tile.
4. Onboard a Service: Click the Onboard button for the desired service to launch the onboarding wizard.
5. Complete the Wizard:
   • Identify: Confirm the auto-detected service name or provide a new one. You can also set a display name that supports UTF-8 characters and locale-specific formatting.
   • Schema: The platform presents the schema it inferred from traffic or fetched from a discovered WSDL. Review the operations.
   • Map: Review the automatically generated mapping from SOAP fields to REST fields. You can adjust field names, data types, and example values.
   • Publish: Choose a URL prefix for the new REST API (e.g., /api/v1/your-service). Clicking Publish generates the OpenAPI v3 specification and deploys the live REST endpoint.

The SOAP service is now available as a REST API. The original SOAP traffic continues to flow through the gateway as before.

Onboarding via Manual WSDL Upload

Use this method if you do not have gateway traffic or wish to define a service before it receives traffic.

How It Works

1. The API publisher uploads a WSDL file or provides a URL to it.
2. The platform parses the WSDL server-side, resolving any imported XSD schemas to understand the service's operations, data types, and faults.
3. The platform presents the parsed schema to the user for review.
4. A deterministic mapping is generated to translate every SOAP element into a REST equivalent.
5. Upon publishing, the platform generates an OpenAPI v3 specification and deploys the live REST endpoint.

Step-by-Step Instructions

1. Open the Wizard: In the sidebar, click Onboard, then select Upload WSDL.
2. Provide the WSDL:
   • By URL: Paste the URL of the WSDL file. The platform will fetch it and resolve any transitive import statements.
   • By file: Drag and drop the .wsdl file. If the WSDL imports other XSD files, upload them in the same transaction.
3. Review the Schema: The platform displays the service definition parsed from the WSDL. Review the following and make adjustments as needed:
   • Operations: Toggle which SOAP operations to expose as REST endpoints.
   • Types: Review inferred field names and example values.
   • Faults: Confirm the default mappings from SOAP faults to HTTP errors.
4. Review the Mapping: As with the auto-discovery flow, review the auto-generated SOAP-to-REST field mappings and edit them if necessary.
5. Publish the Service: Choose a REST URL prefix and click Publish. The platform immediately generates the OpenAPI v3 spec and deploys the service.

Post-Onboarding Tasks

Reviewing the OpenAPI Specification

Once published, the service's OpenAPI v3 specification is available at the following URLs, where your-service is the prefix you chose during publishing:

https://s2r.your-domain.com/api/v1/your-service/openapi.json
https://s2r.your-domain.com/api/v1/your-service/openapi.yaml

You can customize the generated specification from the Mapping tab for the service. Common edits include:

• Display Names: Change programmatic operation names like getCustomerByIdRequest to human-readable summaries like Get Customer By ID.
• Examples: Replace placeholder examples with realistic data. The "Good Examples" tile may suggest values learned from live traffic.
• Field Hints: Add format hints to fields, such as format: email or format: date.
• Locale Strings: Provide descriptions in different languages. The platform fully supports UTF-8, including right-to-left (RTL) languages.

Each edit creates a new, immutable revision of the service configuration. You can roll back to a previous version from the Revisions tab.

Sharing with API Consumers

To enable consumption of the new REST API, provide the following to the consumer team:

• OpenAPI URL: The URL to the openapi.json or openapi.yaml file.
• Base URL: The base URL for making API calls, e.g., https://s2r.your-domain.com/api/v1/your-service/.
• Authentication Credentials: By default, access is controlled by OIDC bearer tokens scoped to the service. Manage credentials in your operator portal under Services → Your service → Access.

Verifying Live Traffic

Monitor the health and traffic of your new REST endpoint from the Operations → Dashboard view.

• Use the Source filter and select runtime to view traffic processed by the new REST endpoint.
• Key performance indicators (KPIs) such as request count, error rate, and p95 latency are updated on a 5-minute aggregation cycle.
• Click a service to drill down into a per-operation breakdown.
• The Top 5 errors tile highlights services with recent failures.

For request-level inspection, use Observability → F5 Live Traffic Log (if enabled) or Observability → Log Search to view individual request/response pairs with full headers and payloads.

Troubleshooting

This section covers common issues encountered during and after onboarding a service.

Setting	Default	Description
timeout	100ms	The timeout for requests to the backend SOAP service. Configurable under Services → Your service → Runtime settings.
retries	2	The number of retries on failure. Configurable under Services → Your service → Runtime settings. Increase with caution, as retries can amplify load on a slow backend.

• Character Encoding Issues: If non-ASCII characters in payloads appear garbled (mojibake), ensure the upstream gateway is setting the Content-Type header with charset=utf-8.
• Payload Size Limit: Synchronous API requests are limited to a maximum payload size of 30MB. Requests exceeding this limit are rejected with an HTTP 413 Payload Too Large status and the error code S2R-RUN-0413. For larger data transfers, use the asynchronous transport path for the service.
• WSDL Import Failures: If the platform fails to parse a WSDL due to unreachable URLs in <import> statements, upload the required XSD schema files along with the WSDL file. The source notes that resolving imports from air-gapped environments is not supported at GA.
• SOAP Faults: SOAP faults from the backend service are automatically mapped to HTTP 4xx or 5xx status codes with a structured JSON error body. You can review and customize these mappings in the UI under Services → Your service → Faults.

See Also

• For troubleshooting discovery and onboarding issues: troubleshooting.md
• For next steps on managing live services: daily-ops.md

---

All SOAP-to-REST docs