Applying Field Name Casing Overrides

The FieldCasingApplyService provides a mechanism for API publishers to control the casing of field names in API responses for a specific operation. This allows for transforming field names from a backend source, such as a SOAP service, into a consistent and conventional format for API consumers.

Configuration is applied at the operation level and supports both a global casing mode and granular, per-field overrides identified by their SOAP XPath.

How it Works

The service exposes a single method, apply, which takes an operation's ID, a global casing mode, and a list of per-field overrides. The process is transactional and updates the operation's mapping configuration in the database. The runtime system then uses this configuration to transform response field names, following a resolution chain of per-field override → operation-level mode → system default → original source name.

The apply method executes the following sequence:

1. Normalize Mode: The provided operationOverride mode is normalized. It is trimmed of whitespace, and if not null or empty, it is matched case-insensitively against a set of canonical modes. If a match is found, the canonical form is used. If no match is found, an error is thrown.
2. Load & Validate Operation: The service retrieves metadata for the target operationId. It then validates that the operation's parent service version is in a mutable state (status is "draft" and it is not active). If the version is active or not a draft, changes are rejected to preserve the integrity of active API versions.
3. Fetch Existing Overrides: The current map of per-field overrides is read from the s2r_operation_mapping table.
4. Merge New Overrides: The provided list of fieldOverrides is merged into the existing map.
   • For each entry, the soapXPath is used as the key.
   • If the name is null or an empty string, the entry for that soapXPath is removed from the map. This allows for clearing a specific override.
   • If a name is provided, it is validated to ensure it is a valid field name before being added to or updated in the map.
5. Persist Changes: The normalized operation mode and the merged map of field overrides (serialized as a JSON object) are written to the s2r_operation_mapping table for the specified operation.
6. Return Result: If the update is successful, an ApplyResult object is returned, containing the final configured state.

The following diagram illustrates the logical flow of the apply method:

flowchart TD
    subgraph FieldCasingApplyService
        A[Call apply()] --> B{Normalize Mode};
        B --> C[Load Operation Metadata];
        C --> D{Is Service Version Mutable?};
        D -- No --> E[Throw S2R-ADM-0410];
        D -- Yes --> F[Read Existing Field Overrides];
        F --> G[Merge New Field Overrides];
        G --> H{Validate Field Names};
        H -- Invalid --> I[Throw S2R-VAL-0499];
        H -- Valid --> J[Update Operation Mapping in Database];
        J --> K{Update Successful?};
        K -- No --> L[Throw S2R-ADM-0404];
        K -- Yes --> M[Return ApplyResult];
    end

    style E fill:#f99,stroke:#333,stroke-width:2px
    style I fill:#f99,stroke:#333,stroke-width:2px
    style L fill:#f99,stroke:#333,stroke-width:2px

API Reference

The service provides a single public method, apply.

apply

Applies a global casing mode and a set of per-field name overrides to an operation.

ApplyResult apply(UUID operationId, String operationOverride, List<FieldEntry> fieldOverrides)

Parameters

Return Value

Returns an ApplyResult object upon successful update.

FieldEntry Data Structure

The fieldOverrides parameter is a list of FieldEntry objects, each defining a single field override.

Example: Setting and Clearing Overrides

While the source does not provide a complete, runnable example, the following illustrates the conceptual usage based on the service's logic.

To set a global camelCase mode for an operation and simultaneously define a custom name for a specific field, you would invoke apply like this:

• operationId: a1b2c3d4-e5f6-7890-1234-567890abcdef
• operationOverride: "camelCase"
• fieldOverrides: A list containing one FieldEntry with:
  • soapXPath: //data/Transaction/USER_ID
  • name: transactionUserId

To later clear the override for USER_ID without affecting the global mode, you would make another call with:

• operationId: a1b2c3d4-e5f6-7890-1234-567890abcdef
• operationOverride: null (or the current value if you don't want to change it)
• fieldOverrides: A list containing one FieldEntry with:
  • soapXPath: //data/Transaction/USER_ID
  • name: null

This removes the //data/Transaction/USER_ID key from the stored override map, causing it to fall back to the camelCase rule defined by operationOverride.

Troubleshooting

When a call to the apply method fails, it throws an ApplyValidationException containing a machine-readable code and a descriptive message.

All SOAP-to-REST docs