Error Shape Overrides for API Operations

Overview

The ErrorShapeApplyService provides a mechanism for API publishers to set a custom error response shape for a single API operation. This allows for fine-grained control over the structure of error payloads returned by the gateway, overriding system-level defaults.

When the API platform generates an error response, it follows a resolution chain to find the appropriate shape:

1. Operation-level override: The value set by this service.
2. System-level default: A platform-wide default shape.
3. Platform built-in: A final fallback shape named s2r-default.

This service modifies the first link in that chain. The override applies to the entire error body; per-field error shape overrides are not supported.

Configuration changes are only permitted on service versions that are in a draft state. Once a service version is active, its operations, including their error shape overrides, become immutable.

How It Works

The apply method orchestrates the process of validating and persisting an operation-specific error shape override. The process is transactional.

sequenceDiagram
    participant Caller
    participant ErrorShapeApplyService
    participant Database

    Caller->>ErrorShapeApplyService: apply(operationId, overrideValue)
    activate ErrorShapeApplyService
    Note over ErrorShapeApplyService: 1. Normalize override value
    Note over ErrorShapeApplyService: 2. Load operation metadata
    ErrorShapeApplyService->>Database: SELECT from s2r_operation, s2r_service_version
    Database-->>ErrorShapeApplyService: Operation metadata (key, version status)
    Note over ErrorShapeApplyService: 3. Validate service version is 'draft'
    alt Validation fails
        ErrorShapeApplyService-->>Caller: ApplyValidationException
    end
    Note over ErrorShapeApplyService: 4. Update operation mapping
    ErrorShapeApplyService->>Database: UPDATE s2r_operation_mapping SET error_shape_override = ?
    Database-->>ErrorShapeApplyService: Update count
    alt Update fails (0 rows)
        ErrorShapeApplyService-->>Caller: ApplyValidationException
    end
    ErrorShapeApplyService-->>Caller: ApplyResult
    deactivate ErrorShapeApplyService

The sequence of operations is as follows:

1. Normalization: The input operationOverride string is normalized. It is trimmed of whitespace. If the value is null, an empty string, or whitespace-only, it is treated as null, which clears any existing override. The normalized value is then compared case-insensitively against a list of valid modes. If it's not a valid mode, the request fails.
2. Metadata Retrieval: The service queries the database to retrieve metadata for the specified operationId, including its operationKey and the status of its parent service version (is_active, status).
3. Mutability Validation: The service checks if the operation's parent service version is editable. An operation can only be modified if its service version is not active (is_active is false) and has a status of draft. If these conditions are not met, the request is rejected.
4. Database Update: If validation succeeds, the service executes a SQL UPDATE statement against the s2r_operation_mapping table. It sets the error_shape_override column to the normalized value for the given operation_id. The update is scoped to the authenticated tenant and only applies to mappings where is_active is true.
5. Return Value: On a successful update, the service returns an ApplyResult object containing the operationId, the operation's operationKey, and the normalized override value that was applied.

Applying an Override

To set or clear an error shape override, invoke the apply method with the target operation's ID and the desired override mode.

Example Invocation

This conceptual example shows how the service method is called.

// Given an instance of ErrorShapeApplyService
ErrorShapeApplyService service = new ErrorShapeApplyService(jdbcTemplate);

// The unique identifier for the target operation
UUID targetOperationId = UUID.fromString("a1b2c3d4-e5f6-7890-1234-567890abcdef");

// The desired error shape mode, e.g., "custom-verbose"
String overrideMode = "custom-verbose";

// Apply the override
try {
    ApplyResult result = service.apply(targetOperationId, overrideMode);
    System.out.println("Successfully applied override '" + result.operationOverride() +
                       "' to operation " + result.operationKey());
} catch (ApplyValidationException e) {
    System.err.println("Failed to apply override: " + e.getMessage());
}

// To clear an override, pass null
ApplyResult clearedResult = service.apply(targetOperationId, null);

Expected Result

A successful call returns an ApplyResult object, confirming that the update was persisted. The object contains the following fields:

API Reference

The service exposes a single method, apply.

apply(UUID operationId, String operationOverride)

Applies an error shape override to a specific operation.

Parameters

Returns

Returns an ApplyResult object upon success.

Throws

• ApplyValidationException: Thrown if the request fails validation. See the Troubleshooting section for details on specific error codes.

Troubleshooting

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

All SOAP-to-REST docs