Binary Handling Overrides for API Operations

Overview

The BinaryHandlingApplyService provides a mechanism for API publishers to apply fine-grained binary content handling overrides for specific API operations. This service allows customization of how binary data from a backend SOAP response is encoded in the final API response, on a per-operation and even per-field basis.

This is necessary when the system-wide default binary handling strategy is not suitable for a particular operation. The runtime uses a resolution chain to determine the encoding for a given field: it first looks for a per-field override, then an operation-level override, and finally falls back to the system default. This service configures the first two links in that chain.

An API publisher invokes this service to modify the configuration of an operation that is part of a service version in a draft state. The service validates the inputs, merges them with existing settings, and persists them to the s2r_operation_mapping table.

How It Works

The service applies a set of overrides to an operation's active mapping in a single, transactional database update. The core logic resides in the apply method.

flowchart TD
    subgraph "apply() Method"
        A[Start] --> B{Normalize Inputs};
        B --> C{Read Existing Field Overrides};
        C --> D{Process New Field Overrides};
        D --> E{Validate Operation Mutability};
        E --> F{Serialize Merged Field Map};
        F --> G{Update Database};
        G --> H[Return Result];
    end

    subgraph "Error Paths"
        B -- Invalid Mode/MIME --> I(Throw S2R-VAL-0497);
        D -- Invalid XPath --> I;
        E -- Version Not Draft --> J(Throw S2R-ADM-0410);
        E -- Operation Not Found --> K(Throw S2R-ADM-0404);
        F -- Serialization Failure --> I;
        G -- No Active Mapping --> K;
    end

The process consists of the following steps:

1. Input Normalization: The operation-level operationOverride mode and dataUrlMimeOverride are normalized. Normalization involves trimming whitespace and, for the mode, converting to lowercase. If a provided mode or MIME type is invalid, the process fails. An empty or null string for either value clears the existing override.

2. Field Map Retrieval: The service reads the existing response_field_binary_handling JSONB data from the s2r_operation_mapping table for the specified operationId. This represents the current set of per-field overrides.

3. Field Override Merging: The service iterates through the fieldOverrides list provided in the request.

   • A soapXPath is required for every field override entry.
   • If an entry's mode is null or blank, the existing override for that soapXPath is removed from the map.
   • If an entry provides a valid mode, it is added to or updated in the map. The mode is validated against a list of supported values. An optional dataUrlMime can be provided and is validated to be a compliant RFC 6838 token.

4. Mutability Validation: The service retrieves metadata for the target operation. It verifies that the operation's parent service version is in a draft state and is not active. Configuration for active or non-draft service versions is immutable, and attempts to modify it will be rejected.

5. Persistence:

   • The newly merged map of field overrides is serialized into a JSON string.
   • A single UPDATE statement is executed against the s2r_operation_mapping table. This statement atomically sets the binary_handling_override (operation mode), binary_data_url_mime_override (operation MIME type), and response_field_binary_handling (per-field map) columns for the row matching the operation_id.
   • The update only targets rows where is_active is true. If no row is updated, it means no active mapping exists for the operation, and an error is thrown.

6. Result: If the transaction is successful, the service returns an ApplyResult object containing the final, applied configuration, including the operation key and the merged map of response field overrides.

API Reference

The service exposes a single method, apply, to manage binary handling overrides.

apply Method

Applies operation-level and field-level binary handling overrides to an active operation mapping.

Parameters

FieldEntry Structure

The fieldOverrides parameter is a list of FieldEntry objects, each with the following structure:

Return Value

The method returns an ApplyResult object upon success.

Troubleshooting

Calls to the apply method may fail with an ApplyValidationException. The exception contains a code and a descriptive message.

All SOAP-to-REST docs