SOAP to REST Transformation: Consume Flow

Overview

The ConsumeSoapHandler is a core runtime component responsible for implementing the "consume" data path. It enables the platform to receive a SOAP request from an API consumer, transform it into a REST request, send it to a configured backend REST service, and then map the REST response back into a SOAP response.

This handler acts as a bridge, allowing API publishers to expose a modern REST-based backend as a traditional SOAP service without modifying the backend. It orchestrates the entire request-response lifecycle for this transformation, including:

• Protocol Transformation: Converts inbound SOAP 1.1 or 1.2 messages to outbound REST requests (e.g., POST, GET) and vice-versa.
• Payload Mapping: Uses publisher-defined mapping rules to transform the structure of the XML payload into a JSON payload and back.
• Validation: Enforces data contracts by validating inbound and outbound payloads against OpenAPI schemas and field-level regular expressions.
• Backend Communication: Manages connectivity, authentication (including mTLS and OAuth 2.0), and retries for the outbound REST call.
• Error Handling: Translates transport errors and non-successful HTTP status codes from the REST backend into compliant SOAP Faults.

The handler is invoked by the runtime controller, which passes it the inbound request details and the configuration for the matched API route. It returns a structured Result containing the complete SOAP response (or fault) to be sent back to the API consumer.

How it Works

The ConsumeSoapHandler processes an inbound SOAP request through a multi-step pipeline to produce a corresponding SOAP response. The process involves parsing, validation, a backend REST call, and response generation.

flowchart TD
    A[API Consumer] -- SOAP Request --> B[API Gateway: ConsumeSoapHandler];
    B --> C{1. Parse SOAP to JSON};
    C --> D{2. Validate Request JSON<br/>(Schema & Regex)};
    D -- Invalid --> J[Build SOAP Fault];
    D -- Valid --> E{3. Prepare REST Request<br/>(URL, Body, Auth)};
    E --> F[4. Dispatch REST Call];
    
    subgraph "Backend"
        G[REST Service]
    end

    F -- Direct or via Relay --> G;
    G -- REST Response --> H{5. Handle REST Response};
    B -- REST Call --> H
    H -- Transport/HTTP Error --> J;
    H -- Success (2xx) --> I{6. Validate REST Response<br/>(Schema & Regex)};
    I -- Invalid --> J;
    I -- Valid --> K{7. Build SOAP Response};
    
    J --> L[SOAP Response (Fault)];
    K --> M[SOAP Response (Success)];

    L --> A;
    M --> A;

Processing Steps

1. Content Validation: The handler first inspects the Content-Type header of the inbound request. It accepts text/xml (SOAP 1.1), application/soap+xml (SOAP 1.2), application/xml, and multipart/related (for MTOM). Any other content type is rejected with a 415 Unsupported Media Type error (S2R-RUN-0408).

2. SOAP Version Detection: It determines the SOAP version (1.1 or 1.2) by inspecting the SOAP envelope's XML namespace. This version is used to format the final SOAP response or fault, ensuring the consumer receives a reply in the version it sent.

3. MTOM Handling: If the request is multipart/related, the handler inlines any attachments referenced by xop:Include elements. It decodes the attachments and embeds them as base64-encoded strings directly into the SOAP body, producing a standard SOAP envelope for the next steps. This process is protected against DoS attacks by enforcing limits on part count and total payload size.

4. SOAP-to-JSON Parsing: The SOAP body is parsed into a JSON object. This transformation is guided by the request_mapping defined in the operation's route configuration. If the inbound SOAP message is malformed or is itself a SOAP Fault, the process is aborted and a soap:Client fault is generated (S2R-RUN-0409).

5. Request Payload Validation: Before contacting the backend, the generated JSON payload undergoes two validation steps:

   • Schema Validation: If an OpenAPI schema is configured for the operation, the JSON is validated against it. A violation results in a 400 Bad Request fault (S2R-VAL-0410).
   • Regex Validation: If the route has requestFieldValidationRegexes configured, specific fields in the JSON are validated against regular expressions. A mismatch also results in a 400 Bad Request fault (S2R-VAL-0411).

6. Outbound REST Request Preparation:

   • URL: The target REST URL is constructed from the backend profile's endpointUrl and the route's restPath.
   • Method: The HTTP method (e.g., POST, GET) is taken from the route's restMethod.
   • Body: For POST/PUT/PATCH requests, the validated JSON becomes the request body. For GET/DELETE requests, the body is empty, and the JSON fields are encoded as URL query string parameters.
   • Headers: Custom headers are added from the backend profile. A unique X-Correlation-Id is also forwarded to the backend to enable distributed tracing.
   • Authentication: If the backend requires oauth2_client_credentials authentication, the handler fetches a bearer token and adds it to the Authorization header. If mTLS is enabled, the appropriate SSL context is prepared for the call.

7. Backend REST Call: The handler dispatches the REST request.

   • Dispatch Mode: The call is either sent directly to the backend or, if dispatch_mode=relay is configured, routed through a relay service for backends in private networks.
   • Retries: The call automatically retries on transient transport errors or 5xx responses, based on the retry_count and retry_backoff_ms settings in the backend profile.
   • Timeouts: Connection and read timeouts are enforced based on the route and backend profile configuration.

8. REST Response Handling:

   • Transport Failures: Network errors, timeouts (S2R-RUN-0424), or circuit breaker trips (S2R-RUN-0529) are mapped to a soap:Server fault.
   • HTTP Errors (4xx/5xx): If the backend returns an HTTP error, it is converted into a SOAP Fault. The platform returns an HTTP 500 to the SOAP consumer, but the fault envelope contains details from the backend response.
   • OAuth 401 Retry: If the backend returns a 401 Unauthorized and OAuth 2.0 is in use, the handler automatically invalidates the cached token, fetches a new one, and retries the request once.

9. Response Payload Validation: For successful (2xx) REST responses, the JSON response body can be validated against the operation's OpenAPI response schema and response-side field regexes. A validation failure in enforce mode results in a soap:Server fault (S2R-VAL-0430 for schema, S2R-VAL-0431 for regex), preventing a malformed response from reaching the consumer.

10. JSON-to-SOAP Building: The validated JSON response is transformed back into a SOAP XML payload using the response_mapping from the route configuration. The resulting SOAP envelope is constructed using the same SOAP version as the original request.

11. Final Result: The handler returns the final SOAP envelope (success or fault) and associated metadata to the controller, which sends the HTTP response to the API consumer.

API Reference

The primary entry point is the handle method. Several overloads exist for backward compatibility, but the full 7-argument version provides complete control.

handle Method

public Result handle(
    RouteMetadata route,
    BackendTargetMetadata backendTarget,
    String inboundSoapBody,
    String authorizationHeader,
    ConversionModes modes,
    UUID correlationId,
    String soapVersion
)

Executes the full consume flow.

• Parameters:

  • route: RouteMetadata containing the configuration for the matched API operation, including mappings, validation rules, and timeouts.
  • backendTarget: BackendTargetMetadata defining the target REST backend, including its URL, authentication method, and retry settings.
  • inboundSoapBody: The raw string content of the inbound SOAP request body.
  • authorizationHeader: The Authorization header from the inbound request, if any.
  • modes: A ConversionModes record specifying overrides for data type conversions.
  • correlationId: A UUID for tracing the request through the system. This ID is forwarded to the backend in the X-Correlation-Id header.
  • soapVersion: A string, either "1.1" or "1.2", indicating the SOAP version of the inbound request. This determines the version of the outbound response.

• Returns: A Result record containing the outcome of the operation.

Result Record

The handle method returns a Result object that encapsulates the outcome.

Helper Methods

• validateContentType(HttpServletRequest request): Checks if the request's Content-Type is a supported SOAP type. Returns a Result object for a 415 error if invalid, or null if valid.
• detectSoapVersion(HttpServletRequest request, String inboundSoapBody): Returns "1.1" or "1.2" based on the SOAP envelope namespace or Content-Type header.
• isMtomInbound(HttpServletRequest request): Returns true if the request Content-Type is multipart/related.
• inlineMtomInbound(String rawBody, String contentType): Parses a multipart/related body, inlines attachments as base64, and returns the resulting plain SOAP envelope as a string.

Configuration

The handler's behavior is primarily configured through the RouteMetadata, BackendTargetMetadata, and ConversionModes objects passed to it. The ConversionModes record provides fine-grained control over data type conversions during the SOAP-to-JSON and JSON-to-SOAP transformations.

ConversionModes Record

This record allows an API publisher to override default conversion behaviors for boolean and null values, both globally and on a per-field basis.

Troubleshooting

When the ConsumeSoapHandler encounters an issue, it generates a SOAP Fault and returns a specific error code in the Result object. These codes are logged and can be used for diagnostics.

All SOAP-to-REST docs