Runtime Route Resolution

Overview

The Runtime Route Repository is a data access component responsible for retrieving comprehensive route and backend configuration from the platform's database. At runtime, when the platform receives an API request, it uses this repository to look up all the metadata required to process that request. This includes matching the request to a specific operation, identifying the backend service to proxy to, and retrieving all associated policies, timeouts, transformation rules, and security settings.

This component solves the problem of dynamically loading an operation's full configuration at request time. It acts as the bridge between the persisted service definitions created by API publishers and the in-memory execution logic of the API runtime.

The repository is called by the core runtime engine. Its primary inputs are request characteristics (HTTP method, path, environment) or specific identifiers (service keys, operation keys). Its primary output is a RouteMetadata object, which is a detailed record containing all configuration for a single API operation, or a collection of BackendTargetMetadata objects for services with multiple backend targets.

How it Works

The repository resolves routes by executing targeted SQL queries against the platform's database. The specific query used depends on the context of the lookup, such as whether it's for a live request or a pre-publication test.

flowchart TD
    subgraph "API Consumer"
        A[API Request]
    end

    subgraph "API Runtime"
        B{Request Context?}
        C[Call findRoutes]
        D[Call findOperationRoute]
        E[Call findByVersionAndOperationDraftAware]
    end

    subgraph "Platform Database"
        F[Query Database Tables <br/>(s2r_runtime_route, s2r_service, s2r_operation, ...)]
    end

    subgraph "Runtime Processing"
        G[Return RouteMetadata]
        H[Process Request <br/>(Transform, Route, Enforce Policies)]
    end

    A --> B
    B -- "Live REST Request" --> C
    B -- "Key-based Lookup" --> D
    B -- "Test Endpoint Request" --> E
    C --> F
    D --> F
    E --> F
    F --> G
    G --> H

Standard Route Resolution

For standard, live traffic, the runtime uses one of two main methods:

1. findRoutes(environment, method, direction): This method performs a lookup based on the incoming request's HTTP method, environment, and traffic direction (PUBLISH or CONSUME). It queries for enabled routes (s2r_runtime_route) associated with an active service version (s2r_service_version) and an enabled operation (s2r_operation). This is the primary mechanism for matching inbound REST requests to their corresponding service operation.

2. findOperationRoute(environment, serviceKey, operationKey): This method provides a more direct lookup for a specific operation, identified by its serviceKey and operationKey within a given environment. It performs a similar query to findRoutes but filters directly on the provided keys. This is used when the target operation is already known.

Both methods join multiple database tables to assemble a complete RouteMetadata object, which aggregates configuration from the service, operation, backend profile, and mapping definitions.

Draft-Aware Route Resolution

A special method, findByVersionAndOperationDraftAware(serviceVersionId, operationKey), exists to support the test-execution endpoint. This method is designed to resolve routes for service versions that are not yet active (i.e., drafts).

Key differences from standard resolution:

• It looks up a route using serviceVersionId and operationKey, bypassing the is_active=true filter on the service version.
• If the service version does not have a published OpenAPI specification, this method can synthesize a minimal OpenAPI v3 document in-memory. It uses the WSDL-derived request schema (o.request_schema) to construct a spec for a single operation. This allows for validation and testing of draft operations before a full OpenAPI specification is generated.
• The lookup is strictly scoped to the current tenant to prevent resolving and testing another tenant's draft services.

Backend Target Resolution

When a service is configured with multiple backend targets (e.g., for weighted routing or failover), the findBackendTargets(serviceIds) method is used to retrieve all associated BackendTargetMetadata records. This method fetches a list of backend profiles for one or more service IDs.

SOAP Operation Key Resolution

For SOAP-based services, the name of an operation in the WSDL (soap_operation_name) may not be the same as the canonical operation_key used within the platform. The resolveOperationKeyBySoapName(environment, serviceKey, soapOperationName) method translates a soap_operation_name from captured traffic or an incoming request into the correct operation_key.

The resolution logic prioritizes an exact match on operation_key first, then falls back to matching on soap_operation_name. This ensures that if a captured operation name happens to be a valid key, it resolves correctly.

API Reference

The RuntimeRouteRepository exposes the following public methods for use by the API runtime.

findRoutes

Finds all active and enabled routes that match a given environment, HTTP method, and traffic direction.

• Signature: List<RouteMetadata> findRoutes(String environment, String method, String direction)
• Parameters:

  Name	Type	Description

| environment | String | The target environment (e.g., "production", "staging"). | | method | String | The HTTP request method (e.g., "GET", "POST"). | | direction | String | The traffic direction, typically PUBLISH for inbound REST APIs. |

• Returns: A List of RouteMetadata objects, sorted by rest_path. Returns an empty list if no routes match.

findOperationRoute

Finds a single active and enabled route by its canonical service and operation keys.

• Signature: RouteMetadata findOperationRoute(String environment, String serviceKey, String operationKey)
• Parameters:

  Name	Type	Description

| environment | String | The target environment. | | serviceKey | String | The unique key identifying the service. | | operationKey | String | The unique key identifying the operation within the service. |

• Returns: A RouteMetadata object if a match is found; otherwise, null.

findByVersionAndOperationDraftAware

Finds a route for a specific service version and operation, regardless of whether the version is active. This is used for testing draft configurations.

• Signature: RouteMetadata findByVersionAndOperationDraftAware(UUID serviceVersionId, String operationKey)
• Parameters:

  Name	Type	Description

| serviceVersionId | UUID | The unique ID of the service version. | | operationKey | String | The unique key identifying the operation within the service version. |

• Returns: A RouteMetadata object if a match is found; otherwise, null. If the service version belongs to another tenant, this method also returns null.

resolveOperationKeyBySoapName

Resolves a SOAP operation name to its canonical operation key for an active service version.

• Signature: String resolveOperationKeyBySoapName(String environment, String serviceKey, String soapOperationName)
• Parameters:

  Name	Type	Description

| environment | String | The target environment. | | serviceKey | String | The unique key of the service. | | soapOperationName | String | The soap_operation_name from the WSDL or captured traffic. |

• Returns: The corresponding operation_key as a String if a match is found; otherwise, null.

findBackendTargets

Retrieves all backend target profiles associated with a list of service IDs.

• Signature: Map<UUID, List<BackendTargetMetadata>> findBackendTargets(List<UUID> serviceIds)
• Parameters:

  Name	Type	Description
  serviceIds	List<UUID>	A list of service IDs to fetch backends for.

• Returns: A Map where keys are service IDs (UUID) and values are lists of BackendTargetMetadata objects. Returns an empty map if the input list is null or empty.

Data Structures

The repository returns data in two primary structures: RouteMetadata and BackendTargetMetadata.

Route Metadata

The RouteMetadata object is a comprehensive record containing all configuration for a single operation. The fields are populated from a large SQL query joining multiple tables.

| Field | Type | Default | Description | --- | --- | --- | | service_id | UUID | — | The unique ID of the service. | | service_version_id | UUID | — | The unique ID of the active service version. | | operation_id | UUID | — | The unique ID of the operation. | | backend_profile_id | UUID | — | The ID of the backend profile associated with this route. May be null. | | default_backend_profile_id | UUID | — | The ID of the default backend profile for the service. | | environment | String | — | The environment this route belongs to. | | direction | String | — | The traffic direction (e.g., PUBLISH, CONSUME). | | rest_method | String | — | The HTTP method for this REST operation. | | rest_path | String | — | The REST URL path for this operation. | | service_key | String | — | The user-defined unique key for the service. | | operation_key | String | — | The user-defined unique key for the operation. | | soap_operation_name | String | — | The operation name as defined in the SOAP contract. | | soap_action | String | — | The SOAPAction header value. | | endpoint_url | String | — | The URL of the backend endpoint. | | auth_type | String | — | The authentication type for the backend (e.g., none, basic). | | secret_ref | String | null | A reference to a secret in a vault. The value is always null in this context; credentials are handled separately. | | soap_namespace | String | — | The target namespace for the SOAP backend. | | soap_version | String | — | The SOAP version (e.g., 1.1, 1.2). | | operation_timeout_ms | int | — | The operation-specific timeout in milliseconds. | | operation_retry_count | int | — | The operation-specific retry count. | | backend_connection_timeout_ms | int | The value of operation_timeout_ms | The connection timeout for the backend, falling back to the operation timeout. | | backend_read_timeout_ms | int | The value of operation_timeout_ms | The read timeout for the backend, falling back to the operation timeout. | | backend_retry_backoff_ms | int | 25 | The backoff delay in milliseconds between retries to the backend. | | debug_enabled | boolean | false | Indicates if debug mode is enabled for the service. | | backend_active | boolean | false | Indicates if the default backend profile is active. | | backend_routing_mode | String | single| The routing mode for multiple backends (e.g., single, weighted). | | backend_health_check_mode | String | none | The health check mode for backends (e.g., none, passive). | | backend_health_check_interval_sec | int | 30 | The interval in seconds for active health checks. | | backend_health_check_timeout_ms | int | 2000 | The timeout in milliseconds for health checks. | | execution_mode | String | sync | The operation execution mode (sync or async). | | callback_path | String | — | The path for asynchronous callbacks. | | callback_auth_mode | String | shared_secret | The authentication mode for asynchronous callbacks. | | callback_secret_ref | String | — | A reference to the secret used for callback authentication. | | async_ack_http_status | int | 202 | The HTTP status code to return for an accepted asynchronous request. | | mapping_version | int | 0 | The version of the active operation mapping. | | mapping_generated_by | String | — | The identifier of the tool or process that generated the mapping. | | request_transform_rules | List<PayloadTransformRuleRecord> | [] | A list of rules for transforming the request payload. | | response_transform_rules | List<PayloadTransformRuleRecord> | [] | A list of rules for transforming the response payload. | | request_mapping | Map<String, Object> | {} | The request mapping definition. | | response_mapping | Map<String, Object> | {} | The response mapping definition. | | fault_mapping | Map<String, Object> | {} | The fault (error) mapping definition. | | request_field_encodings | Map<String, String> | {} | A map of XPath to encoding types for request fields. | | response_field_encodings | Map<String, String> | {} | A map of XPath to encoding types for response fields. | | enforcement_mode | String | shadow| The request validation enforcement mode (e.g., shadow, strict). | | response_enforcement_mode | String | monitor| The response validation enforcement mode (e.g., monitor, strict). | | openapi_spec_json | String | — | The OpenAPI specification for the service version, as a JSON string. | | wsdl_request_schema_json | String | — | The WSDL-derived request schema as a JSON string. Only available in findByVersionAndOperationDraftAware. | | binding_style | String | document | The SOAP binding style (document or rpc). | | operation_headers | List<OperationHeaderRecord> | [] | A list of declared SOAP headers for the operation. | | traffic_capture_enabled | boolean | false | Indicates if traffic capture is enabled for the service. | | traffic_capture_remaining | int | 0 | The remaining number of transactions to capture. | | ... and many more ... | ... | ... | The query returns many fields for fine-grained control over data transformation, including overrides for boolean, null, datetime, numeric, array, and other type handling. These fields follow a pattern like [type]_handling_override, request_field_[type]_handling, and response_field_[type]_handling. |

Backend Target Metadata

The BackendTargetMetadata object contains the configuration for a single backend profile, used when a service has multiple potential backends.

| Field | Type | Default | Description | --- | --- | --- | | id | UUID | — | The unique ID of the backend profile. | profile_name | String | — | The user-defined name for the backend profile. | endpoint_url | String | — | The base URL for the backend service. | wsdl_url | String | — | The URL to the WSDL document for SOAP backends.

| healthcheck_url | String | — | The URL for health checks against this backend. | --- | --- | --- | | host_header | String | — | A custom Host header to send to the backend. | auth_type | String | — | The authentication type for this backend.

| mtls_enabled | boolean | false | Indicates if mutual TLS is enabled for this backend. | --- | --- | --- | | soap_namespace | String | — | The target namespace for the SOAP backend. | soap_version | String | — | The SOAP version (1.1 or 1.2). | connection_timeout_ms | int | — | Connection timeout in milliseconds for this backend. | read_timeout_ms | int | — | Read timeout in milliseconds for this backend. |

| routing_priority | int | — | Priority for routing, with lower numbers being higher priority. |

| routing_weight | int | — | Weight for weighted routing distributions. |

| active | boolean | — | Indicates if this backend profile is active and available for routing. |

| extra_headers | List<ExtraHeader> | [] | A list of custom headers to add to requests to this backend. |

| oauth2_token_endpoint | String | — | The token endpoint URL for OAuth 2.0 client credentials flow. |

| oauth2_client_id | String | — | The client ID for the OAuth 2.0 flow. |

| oauth2_scope | String | — | The scope(s) to request for the OAuth 2.0 token. |

| oauth2_extra_params | List<OAuth2ExtraParam> | [] | A list of extra parameters to include in the OAuth 2.0 token request. |

| credentials | String | — | A JSON string containing credential information. This is an internal representation. |

| dispatch_mode | String | direct | The dispatch mode for the backend, such as direct or relay. |

| relay_id | String | — | The ID of the relay to use if dispatch_mode is relay. |

Troubleshooting

Tenancy Errors

The repository enforces strict tenant boundaries to prevent data leakage.

• Symptom: An error code S2R-TENANCY-UNBOUND is returned.
• Cause: The findBackendTargets method was called in a multi-tenant environment by a process that did not have a tenant context bound to its database connection.
• Meaning: This is a security measure to prevent the system from reading backend credentials (e.g., from a default tenant) when the intended tenant is not specified. The call is blocked.

Route Not Found

If a lookup method fails to find a matching route, it will return null or an empty list.

• Symptom: An API request results in a 404 Not Found error.
• Cause: The call to findRoutes, findOperationRoute, or findByVersionAndOperationDraftAware returned no results. This can happen if:
  • The request's path, method, or keys do not match any configured route.
  • The matched route is disabled (enabled = false).
  • The operation associated with the route is disabled (enabled = false).
  • The service version containing the operation is not active (is_active = false), and the lookup was not using the DraftAware method.
  • The lookup was performed across tenant boundaries (e.g., requesting a serviceVersionId owned by another tenant).

Missing Configuration from Malformed JSON

Several configuration fields, such as extra_headers, request_transform_rules, and various field-level override maps, are stored in the database as JSON. The repository's parsing logic is defensive.

• Symptom: A feature like custom header injection or a payload transformation rule does not execute, but no error is thrown.
• Cause: The corresponding JSON data in the database table (e.g., s2r_backend_profile.extra_headers) is null, empty, or syntactically invalid.
• Meaning: The parser failed to read the configuration but returned an empty list or map to allow the request to proceed without the intended configuration. This prevents a malformed configuration entry from causing a runtime failure, but the behavior will be incorrect. Check the stored JSON for the relevant service or operation.

All SOAP-to-REST docs