Apply Operation-Level Envelope Wrap Overrides

Overview

The Envelope Wrap Apply Service provides a mechanism for API publishers to apply a specific envelope wrapping behavior to a single API operation. This setting overrides any system-level default wrap behavior for that specific operation. The service is designed for operation-level granularity; it does not support per-field overrides, as envelope wrapping is a body-level transformation.

This service acts as the designated writer for the envelope_wrap_override setting on an operation's mapping. The platform's runtime component consumes this setting as part of a resolution chain to determine the final wrap behavior, checking for an override in the following order: operation-level, system-level, and finally a default of 'raw'.

An override can only be applied to an operation belonging to a service version that is in a draft state. Operations within active service versions are immutable.

How it works

When an API publisher invokes the apply service, it performs a sequence of validation and persistence steps to update the operation's envelope wrap override.

sequenceDiagram
    participant API Publisher
    participant EnvelopeWrapApplyService
    participant Database

    API Publisher->>EnvelopeWrapApplyService: apply(operationId, operationOverride)
    activate EnvelopeWrapApplyService

    EnvelopeWrapApplyService->>EnvelopeWrapApplyService: Normalize override value
    Note right of EnvelopeWrapApplyService: Handles nulls, trims whitespace, and<br/>matches case-insensitively against valid modes.

    EnvelopeWrapApplyService->>Database: Query operation and service version metadata
    activate Database
    Database-->>EnvelopeWrapApplyService: Return operationKey, versionStatus, versionActive
    deactivate Database

    alt Operation not found
        EnvelopeWrapApplyService-->>API Publisher: Throw ApplyValidationException (S2R-ADM-0404)
    end

    EnvelopeWrapApplyService->>EnvelopeWrapApplyService: Validate service version is mutable
    Note right of EnvelopeWrapApplyService: Must be in 'draft' status and not active.

    alt Version is immutable
        EnvelopeWrapApplyService-->>API Publisher: Throw ApplyValidationException (S2R-ADM-0410)
    end

    EnvelopeWrapApplyService->>Database: UPDATE s2r_operation_mapping SET envelope_wrap_override
    activate Database
    Database-->>EnvelopeWrapApplyService: Return count of updated rows
    deactivate Database

    alt No active mapping found
        EnvelopeWrapApplyService-->>API Publisher: Throw ApplyValidationException (S2R-ADM-0404)
    end

    EnvelopeWrapApplyService->>API Publisher: Return ApplyResult
    deactivate EnvelopeWrapApplyService

The process is as follows:

1. Normalization: The input operationOverride string is normalized. It is trimmed of whitespace and compared case-insensitively against a list of valid modes. If a valid mode is found, its canonical form is used. Passing null or an empty string clears the override. If the input value is not a valid mode, the service throws an exception.
2. Metadata Retrieval: The service queries the database for metadata associated with the operationId, including its operation_key and the status of its parent service version. If the operation cannot be found, an exception is thrown.
3. Mutability Validation: The service checks if the operation's parent service version is mutable. An operation can only be modified if its service version has a status of draft and is not active. If the version is active or has a different status, the service throws an exception.
4. Persistence: The service executes a SQL UPDATE statement to set the envelope_wrap_override value on the s2r_operation_mapping table for the specified operation_id. The update only targets active mappings (is_active = true).
5. Result: If the update is successful (i.e., exactly one row is updated), the service returns an ApplyResult object containing the operationId, operationKey, and the normalized override value that was persisted. If no active mapping is found to update, an exception is thrown.

Service Method Reference

The service exposes a single method, apply.

apply

apply(UUID operationId, String operationOverride)

Applies or clears an envelope wrap override for a specific operation. The change is persisted to the s2r_operation_mapping table.

Parameters

Returns

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

Throws

• ApplyValidationException: Thrown if the input is invalid or the operation cannot be modified. See the Troubleshooting section for specific error codes and conditions.

Troubleshooting

When a call to the apply service fails, it throws an ApplyValidationException containing a machine-readable error code.

All SOAP-to-REST docs