Manage Conversion Defaults

Overview

The Conversion Defaults API provides administrative endpoints to configure system-wide default policies for data type conversions and transformations. These settings govern the platform's behavior when converting between SOAP and REST formats, ensuring consistency across all integrated APIs.

API publishers with administrative privileges use these endpoints to define policies for a wide range of behaviors, including:

• String pattern validation
• Boolean, numeric, and null value representation
• Date, time, and duration formatting
• JSON field casing and ordering
• SOAP header propagation
• Error response shapes

Changes made via this API are stored in the system settings repository and are audit-logged. The configured defaults are applied globally but can be overridden by more specific configurations at the individual service level.

The API also includes diagnostic endpoints to help identify service definitions that may be affected by these policies, such as finding string fields that lack validation patterns.

How it Works

The ConversionDefaultsController manages settings through a set of RESTful endpoints. Administrators can retrieve the current settings, update them, and run diagnostics.

Retrieving and Updating Settings

• GET /admin/v1/settings/conversion-defaults: Fetches the current effective settings. If a particular setting has not been explicitly configured, the system returns the built-in default value for that policy.
• PUT /admin/v1/settings/conversion-defaults: Updates one or more settings. The request body can contain any combination of the available configuration sections. This allows for partial updates; you only need to provide the sections you wish to change. The system validates each submitted value. Upon successful validation, the new settings are persisted, and an audit event is created containing the state of the settings before and after the change.

The following diagram illustrates the process of updating a conversion default setting.

sequenceDiagram
    participant Admin as API Publisher
    participant API as Conversion Defaults API
    participant DB as System Settings
    participant Log as Audit Log

    Admin->>API: PUT /admin/v1/settings/conversion-defaults (payload)
    activate API
    API->>API: Validate payload (modes, regex, etc.)
    alt Invalid Payload
        API-->>Admin: 400 Bad Request (error details)
    else Valid Payload
        API->>DB: Read current settings (for 'before' state)
        activate DB
        DB-->>API: Current settings
        deactivate DB
        API->>DB: Write updated settings
        activate DB
        DB-->>API: Write confirmation
        deactivate DB
        API->>Log: Record audit event (before/after)
        activate Log
        Log-->>API: Log confirmation
        deactivate Log
        API-->>Admin: 200 OK (new effective settings)
    end
    deactivate API

Diagnostic Endpoints

Two read-only endpoints are available for diagnosing the impact of string validation policies:

• :preview: Provides a system-wide summary of how many string fields in draft service versions are "unconstrained" (i.e., lack a validation regex).
• unconstrained-string-fields: Lists the specific unconstrained string fields for a given service version, providing details like operation ID and field path. This is useful for identifying which fields need attention based on the configured string policy.

API Endpoints

Get Conversion Defaults

Retrieves the complete set of effective conversion default settings.

• Method: GET
• Path: /admin/v1/settings/conversion-defaults
• Success Response: 200 OK
  • Body: A JSON object containing the current values for all conversion policies. If a setting has not been configured, its default value is returned. See the Response Body Fields section for details on the structure.

Update Conversion Defaults

Creates or updates one or more conversion default policies.

• Method: PUT
• Path: /admin/v1/settings/conversion-defaults
• Request Body: A JSON object, ConversionDefaultsRequest, containing the policies to update. See Configuration Reference for all available fields.
• Success Response: 200 OK
  • Body: The full, updated set of effective conversion default settings, identical in structure to the GET response.
• Error Responses:
  • 400 Bad Request: The request body is invalid. See the Troubleshooting section for detailed error codes.

Preview Unconstrained Strings

Returns a summary of unconstrained string fields across all draft service versions. An unconstrained string field is one that does not have a validation regex pattern applied.

• Method: GET
• Path: /admin/v1/settings/conversion-defaults:preview
• Success Response: 200 OK
  • Body: A JSON object with the following fields:
    • totalDraftServiceVersions (Integer): Total number of service versions in a draft state.
    • totalStringFields (Integer): Total number of string fields across all draft versions.
    • unconstrainedFieldsCount (Integer): Total number of unconstrained string fields across all draft versions.
    • perVersionSummary (Array of Objects): A list of summaries for each draft version with unconstrained fields. Each object contains:
      • serviceVersionId (UUID)
      • serviceKey (String)
      • environment (String)
      • versionNo (Integer)
      • totalStringFields (Integer)
      • unconstrainedCount (Integer)
    • computedAt (String): The ISO 8601 timestamp when the summary was generated.

List Unconstrained Strings for a Version

Returns a detailed list of all unconstrained string fields for a specific service version.

• Method: GET
• Path: /admin/v1/services/{serviceId}/versions/{versionId}/unconstrained-string-fields
• Path Parameters:
  • serviceId (UUID): The unique identifier of the service.
  • versionId (UUID): The unique identifier of the service version.
• Success Response: 200 OK
  • Body: A JSON object with the following fields:
    • serviceId (UUID): The service ID from the request.
    • serviceVersionId (UUID): The service version ID from the request.
    • totalStringFields (Integer): Total number of string fields in this version.
    • unconstrainedCount (Integer): Number of unconstrained string fields in this version.
    • fields (Array of Objects): A list of unconstrained fields. Each object contains:
      • operationId (String)
      • operationKey (String)
      • jsonPath (String)
      • soapXPath (String)
      • direction (String)
      • fieldName (String)
      • xsdType (String)
    • computedAt (String): The ISO 8601 timestamp when the list was generated.

Configuration Reference

The PUT /admin/v1/settings/conversion-defaults endpoint accepts a ConversionDefaultsRequest JSON object. The following tables describe all possible fields in this object.

Top-Level Request Fields

These fields are at the root of the request body.

String Handling

Defines the policy for string fields without a validation pattern. Corresponds to the stringWithoutRegex object.

Boolean Handling

Defines the policy for boolean value conversion. Corresponds to the booleanHandling object.

Upstream Failure Status Handling

Defines how upstream failure status codes are handled. Corresponds to the upstreamFailureStatus object.

Null Handling

Defines how null values are represented in requests and responses. Corresponds to the nullHandling object. Fields are optional; if a direction is omitted, its current setting is preserved.

Date/Time Handling

Defines formatting for date and time values. Corresponds to the datetimeHandling object. Fields are optional; if omitted, current settings are preserved.

Array Collapse Handling

Defines how to handle arrays that contain a single element. Corresponds to the arrayCollapse object.

Numeric Handling

Defines the policy for numeric type conversion. Corresponds to the numericHandling object.

Whitespace Handling

Defines the policy for handling whitespace in string values. Corresponds to the whitespaceHandling object.

Binary Data Handling

Defines the encoding for binary data (xsd:base64Binary). Corresponds to the binaryHandling object.

Duration Handling

Defines the formatting for xsd:duration values. Corresponds to the durationHandling object.

Required Field Handling

Defines how to handle fields marked as required but are empty. Corresponds to the requiredHandling object.

Header Propagation

Defines the policy for propagating SOAP headers. Corresponds to the headerPropagation object.

Field Casing

Defines the casing for JSON field names. Corresponds to the fieldCasing object. Input is case-insensitive, but stored and returned in a canonical format.

Response Envelope Wrapping

Defines if and how JSON responses are wrapped in an envelope. Corresponds to the envelopeWrap object.

Error Shape

Defines the structure of JSON error responses. Corresponds to the errorShape object.

xsi:type Handling

Defines how to handle xsi:type attributes from SOAP, which are used for polymorphism. Corresponds to the xsiTypeHandling object.

Field Ordering

Defines the order of fields in JSON response objects. Corresponds to the fieldOrdering object.

Integer Range Bounds

Defines whether to emit minimum/maximum bounds for int32 and int64 types in the generated OpenAPI Specification. Corresponds to the integerRangeBounds object.

Response Body Fields

The response body for GET /admin/v1/settings/conversion-defaults and a successful PUT contains all the fields listed in the Configuration Reference, reflecting the current effective settings. It also includes the following field:

Additionally, for backward compatibility, the response includes mode, genericRegex, and patternStrategy at the top level, which are duplicates of the fields within the stringWithoutRegex object.

Troubleshooting

When a PUT request is invalid, the API returns a 400 Bad Request status with a JSON body containing an error code and message.

All SOAP-to-REST docs