Configuring Service Backends

{/* AUTO-GENERATED from the docs pipeline — do not edit by hand /} {/ source doc_id: prd-s2r-docs-public-knowledgebase-onboarding-configure-backend · version: 1.7.7 */}

Overview

A service's backend profile contains the configuration that the API platform runtime uses to connect to the upstream service. It defines where and how the runtime sends the converted API call.

• 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 settings are managed in the UI under Services → your service → Backend. When a service is created from a WSDL file, the platform infers an initial endpoint and SOAP version, which you must then confirm and complete in the backend profile.

How it works

The backend profile is central to the runtime's ability to process requests. The configuration flow involves initial setup, authentication, and optional multi-backend routing for high availability.

Initial Configuration

When you import a WSDL, the platform attempts to pre-fill the backend profile by inspecting the soap:address and binding information within the file. You are responsible for verifying these inferred settings and completing the configuration, including authentication details, timeouts, and retry policies.

Multi-Backend Routing and Failover

Since v1.0, a service can be configured with multiple backends to enable routing and failover. This enhances service reliability.

• Multiple Backends: You can register more than one backend for a single service. One is designated as the default.
• Health Checks: The runtime performs periodic health probes against backends. The results of these checks inform routing decisions, allowing the runtime to avoid sending traffic to failing backends.
• Failover: If the primary backend is unavailable, the runtime automatically fails over to the next configured backend in the specified order. This failover process operates within the bounds of the operation's timeout and retry settings.
• Independent Configuration: Each backend in a multi-backend setup can have its own distinct endpoint, transport settings, and authentication credentials. This allows for configurations like a primary and a fallback service hosted in different environments.

The following diagram illustrates the failover flow when a primary backend is unavailable.

flowchart TD
    A[API Consumer Request] --> B[API Platform];
    subgraph B
        C[Route to Backend] --> D{Primary Backend Available?};
        D -- Yes --> E[Call Primary Backend];
        D -- No --> F{Failover to Next Backend};
        F --> G[Call Fallback Backend];
        E --> H[Return Response];
        G --> H;
    end
    E --> I[Primary Backend Service];
    G --> J[Fallback Backend Service];

Credential Security

All credentials stored in the backend profile, such as passwords or tokens, are encrypted at rest using pgcrypto.

Before relying on a new or updated backend configuration, use the test connection action in the UI to validate the endpoint URL and authentication settings. A successful test confirms that the runtime can connect to the backend.

Backend Configuration Reference

The following settings are available in the backend profile, configured under Services → your service → Backend.

Authentication

The following authentication types are supported for outbound connections to the backend service.

Timeout and Retry Tuning

The default timeout (100 ms) and retry count (2) are optimized for fast, low-latency backends, such as those co-located in the same virtual private cloud (VPC).

• Override Defaults: For specific operations that are known to be slower, you can override the default timeout and retry values on a per-operation basis.
• Bounded Failures: The failure behavior is strictly bounded. Retries are not indefinite. Increase timeouts with caution, as slow backends can degrade overall system performance, especially under retry conditions.
• Publish Readiness: The configured timeout and retry policy are indirectly validated during the publishing process. If the SOAP test fails because the backend cannot be reached with the configured settings, the service publish will be blocked until the issue is corrected.

Troubleshooting

Connection and Configuration Validation

A common failure point is an incorrect backend configuration, such as a wrong endpoint URL or invalid credentials.

• Symptom: API calls fail, and the service may be blocked from being published.
• Cause: The runtime cannot establish a connection with the backend service using the provided profile settings.
• Resolution: Use the test connection action under Services → your service → Backend to validate the endpoint and authentication. Correct any errors and re-test until the connection succeeds.

Oversized Payloads

The runtime imposes a size limit on synchronous request payloads to protect system stability.

• Symptom: Requests fail with an HTTP 413 Payload Too Large status code. The corresponding internal error code is S2R-RUN-0413.
• Cause: The request payload exceeds the 30 MB ceiling.
• Resolution: Ensure that API consumers send payloads smaller than 30 MB. For use cases involving larger data, an asynchronous processing pattern may be required. The source does not specify options for this.

See Also

• Generate & review the OpenAPI
• Publish & version a service
• Conversion options reference (see the upstream-failure-status option)
• Backend credential encryption

All SOAP-to-REST docs