Configure Per-Operation SOAP Fault Detail Exposure

Overview

This document describes how to configure the level of detail exposed to an API consumer when a backend SOAP service returns a fault. The platform allows API publishers to set a per-operation override, which controls whether the full backend fault message or a sanitized version is passed through to the REST response.

This feature solves the problem of balancing debugging needs with security concerns. During development, an API publisher may need to see the complete, verbose fault details from a backend service. In a production environment, exposing these details could leak sensitive information about the backend infrastructure.

The override is applied to a specific operation's active mapping. It can be set to one of two modes:

• full: Exposes more backend fault detail to the REST client.
• safe: Exposes a sanitized, minimal fault detail.

If no override is set for an operation (i.e., the value is null), it inherits the system-wide default behavior.

This configuration can only be modified on service versions that are in a draft state and not active, preventing changes to live APIs.

How it Works

The process of applying a fault detail exposure override is handled by the FaultDetailExposureApplyService. When an API publisher requests to change the setting for an operation, the service performs a sequence of validation and update steps.

sequenceDiagram
    participant P as API Publisher
    participant S as Admin Service
    participant DB as Database

    P->>S: apply(operationId, mode)
    S->>S: 1. Normalize and validate mode
    alt Invalid Mode
        S-->>P: Error (S2R-VAL-0482)
    end
    S->>DB: 2. Load operation & version metadata
    alt Operation Not Found
        DB-->>S: Not found
        S-->>P: Error (S2R-ADM-0404)
    end
    DB-->>S: Return metadata
    S->>S: 3. Validate service version is mutable
    alt Version is Active/Not Draft
        S-->>P: Error (S2R-ADM-0410)
    end
    S->>DB: 4. Update fault_detail_exposure_override
    alt No Active Mapping Found
        DB-->>S: 0 rows updated
        S-->>P: Error (S2R-ADM-0404)
    end
    DB-->>S: 1 row updated
    S->>DB: 5. Read current override value
    DB-->>S: Return override value
    S-->>P: Success (ApplyResult)

The process consists of the following steps:

1. Input Validation: The service first validates the provided mode value. It is normalized by trimming whitespace and converting to lowercase. Any value other than safe or full is rejected. Providing null or an empty string is a valid way to clear the override.
2. Operation Metadata Retrieval: The service queries the database for the specified operationId to retrieve its metadata, including the status of its parent service version. If the operation does not exist, the process fails.
3. Mutability Check: The service checks if the operation's parent service version is mutable. An override can only be applied if the service version has a status of draft and is not active (is_active = false). This prevents changes to live API definitions.
4. Database Update: If all validations pass, the service executes a SQL UPDATE statement on the s2r_operation_mapping table. It sets the fault_detail_exposure_override column to the normalized mode for the row matching the operation_id where is_active = true.
5. Result Confirmation: After a successful update, the service reads the newly persisted value from the database and returns it in an ApplyResult object, confirming the change.

Applying an Override

To set or clear the fault detail exposure override for an operation, you invoke the apply service method with the operation's ID and the desired mode.

Example

This example sets the fault detail exposure mode to full for an operation with a specific UUID.

Request Parameters:

• operationId: a1b2c3d4-e5f6-7890-1234-567890abcdef
• mode: "full"

Conceptual Invocation:

// Conceptually, an admin client would trigger this service call.
// The actual mechanism is via an internal administrative API endpoint.

UUID operationId = UUID.fromString("a1b2c3d4-e5f6-7890-1234-567890abcdef");
String mode = "full";

ApplyResult result = faultDetailExposureApplyService.apply(operationId, mode);

Expected Result:

A successful call returns an ApplyResult object containing the operation ID, its key, and the override that was just applied.

{
  "operationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "operationKey": "my-soap-operation",
  "operationOverride": "full"
}

To clear the override and revert to the system default, provide null or an empty string for the mode parameter.

API Reference

The FaultDetailExposureApplyService provides the following public methods.

apply

Applies a fault detail exposure override to an operation's active mapping.

ApplyResult apply(UUID operationId, String mode)

Parameters

Return Value

On success, returns an ApplyResult object with the following fields:

Exceptions

This method can throw an ApplyValidationException for the error conditions listed in the Troubleshooting section.

readOperationOverride

Reads the current fault detail exposure override for a given operation.

String readOperationOverride(UUID operationId)

Parameters

Return Value

Returns a String representing the current override (safe or full). Returns null if no override is set for the operation's active mapping.

Troubleshooting

When a call to the apply method fails, it throws an ApplyValidationException containing an error code. The following table details the possible codes and their meanings.

See Also

• Upstream Failure Status Mapping: The UpstreamFailureStatusApplyService provides a similar per-operation override mechanism for controlling HTTP status codes on upstream failures.

All SOAP-to-REST docs