Configure Backend Service Profiles

Overview

A backend profile defines the connection and authentication details for the upstream service that the runtime calls after converting a request. Every service requires a backend profile.

The role of the backend depends on the service direction:

• For a Publish service (SOAP-to-REST), the backend is your original SOAP service.
• For a Consume service (REST-to-SOAP), the backend is the target REST service.

Backend profiles are managed under Services → your service → Backend. When you create a service from a WSDL, the platform infers an initial endpoint and SOAP version from the WSDL's soap:address and binding information, which you must then confirm and complete.

How It Works

When the runtime processes an incoming request for a service, it consults the service's backend profile to determine how to proxy the converted call. The profile dictates the target endpoint URL, authentication credentials, transport settings, and failure handling policies like timeouts and retries.

For services with multiple backends configured, the runtime uses health checks and a defined failover order to ensure high availability.

The following diagram illustrates the request flow for a service with a primary and a failover backend:

flowchart TD
    subgraph "Request Flow"
        direction TD
        A[API Consumer] --> B{S2R Runtime};
        B -- "Sends request to" --> C[Primary Backend];
        C -- "Fails or is unhealthy" --> B;
        B -- "Fails over to" --> D[Secondary Backend];
        D -- "Returns response" --> B;
        B -- "Returns response to" --> A;
    end

Core Backend Settings

These settings define the fundamental connection parameters for a backend. The default timeout and retry values are inherited from system-wide settings but can be overridden for each operation.

Authentication

Since v1.0, the platform supports several authentication types for securing connections to the backend service. Mutual TLS (mTLS) can be enabled in conjunction with any other authentication type.

Credential Security

All backend credentials, such as passwords and tokens, are encrypted at rest using pgcrypto. The encryption key is a critical secret configured at deployment time.

Multi-Backend Routing and Failover

Since v1.0, a service can be configured with more than one backend to improve reliability and support complex routing scenarios. This is configured under Services → your service → Backend.

Key capabilities include:

• Multi-backend routing: Register multiple backends and designate one as the default.
• Failover: If the primary backend becomes unavailable, the runtime automatically fails over to the next backend in the configured order. This process respects the operation's overall timeout and retry limits.
• Backend health checks: The runtime performs periodic health probes against configured backends. The results of these checks inform routing decisions, allowing the runtime to proactively avoid sending traffic to failing backends.
• Per-backend configuration: Each backend in a multi-backend setup can have its own distinct endpoint, transport settings, and authentication credentials. This allows you to configure a fallback backend that may reside in a different environment or require different credentials.

Troubleshooting

Timeouts and Retries

The default timeout of 100ms and 2 retries are optimized for fast, low-latency backends. If a specific backend operation is known to be slow, you can override these defaults on a per-operation basis. Be aware that failure behavior is bounded; retries do not execute indefinitely.

Oversized Payloads

The runtime rejects synchronous requests with payloads larger than 30 MB. If a request exceeds this limit, the client will receive an HTTP 413 Payload Too Large response with the error code S2R-RUN-0413.

Failed Connection Tests

The backend configuration, including authentication and timeout settings, is validated by the "SOAP test" during the publishing process. If the runtime cannot successfully connect to the backend using the provided profile, the test will fail, and the service cannot be published. Correct the backend configuration and re-run the test to proceed.

See Also

• Consume Direction for REST Backends
• Security for Backend Credential Encryption
• Publish and Version a Service
• Generate and Review the OpenAPI Specification
• Conversion Options Reference (see upstream-failure-status to control the HTTP status code returned on backend failure)

All SOAP-to-REST docs