Configure Operation-Level JSON Field Ordering

Overview

The FieldOrderingApplyService provides a mechanism for API publishers to set a JSON field ordering override on a per-operation basis. This service allows fine-grained control over the serialization of response bodies, which can be necessary for consumers that depend on a stable field order.

This service modifies a single API operation's configuration. It is a "single writer" service, meaning it only persists the override value for a specific operation. The logic for resolving the final field order—which checks for an override at the operation level, then a system-wide default, and finally falls back to the order defined in the API schema—is handled by the API runtime, not this service.

An override can only be applied to an operation that belongs to a service version in a draft state. It is not possible to modify the field ordering for an active, published service version.

How it Works

The service applies an override by updating the field_ordering_override property for a specific operation mapping in the database. The process is executed within a single transaction.

flowchart TD
    subgraph Field Ordering Apply Service
        A[Input: operationId, override] --> B{Normalize Override String};
        B -- valid --> C{Load Operation Metadata};
        B -- invalid --> Throw[Throw S2R-VAL-0499];
        C -- not found --> Throw404_1[Throw S2R-ADM-0404];
        C -- found --> D{Validate Mutability};
        D -- not mutable --> Throw410[Throw S2R-ADM-0410];
        D -- mutable --> E[Update s2r_operation_mapping table];
        E -- 0 rows updated --> Throw404_2[Throw S2R-ADM-0404];
        E -- 1+ rows updated --> F[Return ApplyResult];
    end

The sequence of operations is as follows:

1. Normalize Input: The apply method receives an operationId and an operationOverride string. The override string is normalized:

   • null or whitespace-only strings are treated as null, which clears any existing override.
   • The string is checked against a list of canonical and valid modes.
   • If the mode is invalid, the service throws an ApplyValidationException (S2R-VAL-0499).

2. Load Metadata: The service queries the s2r_operation and s2r_service_version tables to retrieve metadata for the given operationId, including its service version status. If the operation is not found, it throws an ApplyValidationException (S2R-ADM-0404).

3. Validate Mutability: The service checks if the operation's associated service version is mutable. An operation is considered immutable if its service version is active (is_active = true) or its status is not draft. If the version is immutable, the service throws an ApplyValidationException (S2R-ADM-0410).

4. Persist Override: If validation passes, the service executes a SQL UPDATE statement to set the field_ordering_override column in the s2r_operation_mapping table for the specified operation_id. The update only targets active mappings (is_active = true) and is scoped to the current tenant.

5. Verify Update: The service checks if any rows were updated. If no rows were affected, it means no active mapping was found for the operation, and the service throws an ApplyValidationException (S2R-ADM-0404).

6. Return Result: On successful update, the service returns an ApplyResult object containing the operationId, the operation's operationKey, and the normalized operationOverride value that was persisted.

API Reference

The service exposes a single method, apply, for setting the override.

apply

ApplyResult apply(UUID operationId, String operationOverride)

Applies a field ordering override to a single operation.

Parameters

Return Value

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

Example

While the source does not provide a complete, runnable example, a successful invocation would return a payload similar to the following:

{
  "operationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "operationKey": "getUserProfile",
  "operationOverride": "alphabetical"
}

Troubleshooting

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

All SOAP-to-REST docs