Configure Array Collapse Overrides for API Operations

Overview

The ArrayCollapseApplyService provides a mechanism for API publishers to control how single-element arrays in backend SOAP responses are represented in the final transformed response. By default, the system follows a platform-wide behavior for array handling. This service allows for granular overrides at two levels for any given API operation:

1. Operation-level Override: A single setting that applies to all fields in the response of a specific operation.
2. Per-field Override: A more specific setting that targets a single field within the response, identified by its soapXPath.

This configuration is applied to an s2r_operation_mapping and is only possible for operations that are part of a service version in a draft, non-active state. The runtime resolution chain for array collapsing is per-field, then per-mapping (operation), then the system default. This service manages the first two levels of that chain.

The primary function of this service is the apply method, which takes an operation ID and a set of overrides, validates them, and persists them to the database.

How It Works

The ArrayCollapseApplyService modifies an operation's array collapse settings within a database transaction. The process ensures that changes are atomic and are only applied if all conditions are met.

flowchart TD
    subgraph "Array Collapse Configuration Flow"
        A[API Publisher calls apply function] --> B{Validate operation-level override};
        B -- Invalid --> F[Fail: Invalid override mode];
        B -- Valid --> C[Load existing per-field overrides from DB];
        C --> D[Merge new per-field overrides];
        D --> E{Validate each per-field override};
        E -- Invalid --> F;
        E -- Valid --> G[Load operation metadata from DB];
        G --> H{Is operation's service version editable?};
        H -- No --> I[Fail: Service version is immutable];
        H -- Yes --> J[Serialize final per-field overrides to JSON];
        J --> K[Persist operation-level and per-field overrides to DB];
        K --> L{Was mapping found and updated?};
        L -- No --> M[Fail: Active mapping not found];
        L -- Yes --> N[Return success with final configuration];
    end

The apply method executes the following sequence:

1. Input Validation: It first normalizes and validates the operationOverride mode. The mode value is trimmed and converted to lowercase. It must be one of the system-defined valid modes.
2. Load Existing Configuration: It queries the s2r_operation_mapping table to retrieve the current response_field_array_collapse JSONB content for the specified operationId.
3. Merge Overrides: The service constructs a new map of per-field overrides. It starts with the existing overrides and then iterates through the provided fieldOverrides list.
   • For each FieldEntry, if the mode is null or blank, the entry for that soapXPath is removed from the map, effectively clearing the override.
   • If the mode is a non-blank string, it is validated. If valid, it is added to the map, creating or replacing the override for that soapXPath.
   • An invalid mode or a missing soapXPath in a FieldEntry will halt the process and throw a validation exception.
4. Check Mutability: The service fetches the operation's metadata to verify that its 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 is false).
5. Persist Changes: The merged map of field overrides is serialized into a JSON string. The service then executes a SQL UPDATE on the s2r_operation_mapping table to set the array_collapse_override and response_field_array_collapse columns for the given operationId. The update only targets active mappings (is_active = true) within the current tenant's scope.
6. Return Result: If the update is successful (i.e., at least one row was updated), the method returns an ApplyResult object containing the operation's ID and key, the applied operation-level override, and the complete map of final per-field overrides. If no active mapping is found to update, it throws an exception.

Example Invocation

To configure array collapse overrides, you invoke the apply method with the target operation's ID and the desired overrides. The following conceptual example shows how to set an operation-level override and define two field-specific overrides.

This example sets a default behavior for the operation and then specifies a different behavior for one field (//ns1:item) while clearing any existing override for another field (//ns1:detail).

// This is a conceptual example. Actual invocation depends on the client implementation.

UUID targetOperationId = UUID.fromString("...");
String operationLevelOverride = "collapse"; // A valid mode string

List<FieldEntry> fieldLevelOverrides = List.of(
    // Set a specific mode for the 'item' field
    new FieldEntry("//ns1:item", "collapse"),

    // Clear any existing override for the 'detail' field by passing null mode
    new FieldEntry("//ns1:detail", null)
);

try {
    ApplyResult result = arrayCollapseApplyService.apply(
        targetOperationId,
        operationLevelOverride,
        fieldLevelOverrides
    );

    System.out.println("Successfully applied overrides for operation: " + result.operationKey());
    System.out.println("Final field overrides: " + result.responseFieldOverrides());

} catch (ApplyValidationException e) {
    System.err.println("Failed to apply overrides: " + e.code() + " - " + e.getMessage());
}

Expected Result

If successful, the apply method returns an ApplyResult object. The responseFieldOverrides map in the result will contain {"//ns1:item": "collapse"}. The entry for //ns1:detail will have been removed. The operation-level override will be set to collapse.

API Reference

The service exposes a single method, apply, for managing overrides.

apply method

Applies operation-level and per-field array collapse overrides to an active operation mapping. The operation must belong to a mutable service version.

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

Parameters

FieldEntry Record

Defines a single per-field override.

• mode | String | No | The array collapse mode for this specific field. If null or blank, any existing override for this soapXPath will be removed. Otherwise, it must be one of the valid modes. |

Returns

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

• operationKey | String | The key of the operation that was modified. - |
• operationOverride | String | The normalized operation-level override mode that was applied. - |
• responseFieldOverrides | Map<String, String> | The complete, final map of per-field overrides (soapXPath to mode) for the operation after the merge. - |

Troubleshooting

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

• S2R-ADM-0410 | mapping-immutable: the operation's service version is not editable | The operation belongs to a service version that is not in a draft state or is currently active. Configuration for such operations is immutable. - |

See Also

• API Operation Management
• Service Version Lifecycle

All SOAP-to-REST docs