ApiToApiConnectorModule Migration Guide

Overview

ApiToApiConnectorModule is a retired compatibility shell. Version 1.0 accepted separate caller-controlled source and target URLs, arbitrary credential-bearing headers, query parameters, mapping formulas, batch endpoints, and retry behavior inside one task. It used a default HTTP client, did not bind credentials to either destination, did not bound response or batch sizes, could suppress mapping failures, and claimed universal idempotency across external writes. Workflow Studio exposed no declared inputs and only one configuration field, so the visible contract did not describe the behavior being executed.

Version 2.0 keeps the Java class and Spring bean loadable so saved workflows can be inspected and migrated, but hides it from backend discovery and the Workflow Studio fallback catalog. Execution now fails closed with MODULE_RETIRED, performs no network, credential, mapping, batching, retry, or write behavior, and identifies RestApiModule, SchemaMapperModule, and a second RestApiModule as the governed migration path.

Usage

1. Find saved workflow tasks whose module type is ApiToApiConnectorModule or fallback type connector.api.bridge.
2. Inventory the exact source origin, target origin, authentication mode, selected response path, mapping rules, expected statuses, and prior write receipts.
3. Rotate credentials that version 1.0 stored in source_api.headers or target_api.headers.
4. Replace the bridge with a bounded source RestApiModule, a local SchemaMapperModule, and a bounded target RestApiModule.
5. Bind source and target credentials to separate least-privilege READY IntegrationAccount records.
6. Require confirmWrite:true for the target step, choose a stable caller correlation key when the provider supports one, and reconcile ambiguous provider writes before retrying.

Inputs

The retired shell accepts legacy inputs only for compatibility and ignores them without reading or emitting their values:

Name	Type	Required	Description
source_api	object	no	Legacy source URL, method, headers, query parameters, and data path; never sent.
target_api	object	no	Legacy target URL, method, headers, batching, and endpoint data; never sent.
schema_mapping	array	no	Legacy field and formula mappings; never evaluated.
error_strategy	string	no	Legacy continue/stop behavior; never controls retries.
dry_run	boolean	no	Legacy flag; the shell is always side-effect free.

The replacement source and target steps use the canonical RestApiModule inputs: method, url, optional bounded body and non-secret headers, authMode, confirmWrite, idempotencyKey, expectedStatus, timeoutMs, maxResponseBytes, maxAttempts, parseJson, responsePath, and failOnError. SchemaMapperModule consumes current workflow state through the standard field-mapping ABI and emits mapped_data.

Outputs

The compatibility shell always returns:

Name	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, retryable:false, migration targets, and required action.

Each REST replacement step returns normalized method, safe URL, HTTP status, duration, attempts, bounded response data, allowlisted response headers, optional external receipt, retryability, and a safe error object. The mapping step returns mapped_data and status.

IntegrationAccount Requirements

The retired shell reads no IntegrationAccount and no legacy credential field. Remove and rotate any bearer token, API key, Basic secret, cookie, signature, or other credential stored in the old header maps.

For each authenticated replacement REST step:

• use its own READY IntegrationAccount;
• set accountId to the exact allowed HTTPS base URL;
• store bearer, API-key, or Basic credentials only in the account's SecureFields;
• grant only the provider scopes needed by that one read or write; and
• never place authorization, API keys, cookies, or credentials in workflow headers, bodies, URLs, or mapping state.

Configuration

The retired module has no active configuration. Saved source/target request objects, header maps, batch settings, error handling, mapping formulas, output aliases, and retry settings are ignored.

Configure the replacement as three separate tasks. A conceptual source read is:

{
  "method": "GET",
  "url": "/v1/users",
  "authMode": "bearer",
  "responsePath": "data",
  "expectedStatus": [200],
  "maxAttempts": 2,
  "maxResponseBytes": 1048576
}

Map only required fields into mapped_data, then configure the target write:

{
  "method": "POST",
  "url": "/v1/customers",
  "authMode": "bearer",
  "body": "{{mapped_data}}",
  "confirmWrite": true,
  "idempotencyKey": "customer-sync-{{source_id}}",
  "expectedStatus": [201],
  "maxAttempts": 1
}

Workflow Studio resolves templated state according to the normal module input-mapping ABI; do not send the literal example placeholder as provider data.

Operations

ApiToApiConnectorModule supports only one compatibility operation: reject execution and identify the migration path.

The replacement sequence supports:

1. one bounded REST read with conservative retries;
2. one deterministic local field mapping; and
3. one explicitly confirmed, single-attempt REST write.

Splitting the bridge makes destination binding, credentials, limits, failure state, approvals, and provider receipts independently observable.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace the task; retrying cannot re-enable the bridge.
Legacy headers contain secrets	Values are ignored and never emitted.	Remove and rotate every exposed credential.
Destination does not match IntegrationAccount.accountId	Replacement fails before sending credentials.	Bind the account to the exact HTTPS base URL.
Redirect is returned	Replacement does not follow it.	Configure and approve the canonical destination directly.
Response exceeds the configured bound	Replacement fails with a safe size error.	Narrow the response or use provider pagination.
Source read times out or returns a transient status	Only bounded read attempts are eligible.	Retry within the configured limit or resume from a known cursor.
Target write is rejected or times out	The write is not retried automatically.	Reconcile provider state and the correlation key before a deliberate new attempt.
Mapping is missing or invalid	The mapping task fails locally before the target write.	Correct the explicit field mapping and rerun from durable source state.

Example

A saved legacy task reaches the compatibility shell:

{
  "source_api": { "url": "/v1/users", "method": "GET" },
  "target_api": {
    "url": "/v1/customers",
    "method": "POST"
  }
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "ApiToApiConnectorModule is retired; compose governed REST, mapping, and REST steps",
    "retryable": false,
    "migrationTargets": ["RestApiModule", "SchemaMapperModule", "RestApiModule"]
  }
}

Notes

• Pagination: the compatibility shell never paginates. Replacement pagination must use a provider-defined cursor or page token in a bounded workflow loop; do not synthesize unbounded reads.
• Limits: the shell returns immediately. Each REST step caps URL, headers, request body, response body, timeout, expected statuses, and read attempts. Mapping runs separately against bounded workflow state.
• Idempotency: the compatibility response is deterministic and side-effect free. Reads may retry conservatively. External writes are not universally idempotent; use a provider-supported key and reconcile receipts before retrying.
• API constraints: replacement calls require HTTPS, reject credentials in URLs and headers, disable redirects, and bind authenticated destinations to READY IntegrationAccounts.
• Destructive behavior: the shell performs none. A target POST, PUT, PATCH, or DELETE requires confirmWrite:true and remains a single attempt.
• Runtime deployment: source, tests, and documentation can be merged and published independently, but live Workflow Studio will continue to show version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, secret non-disclosure, repeatability, backend discovery exclusion, direct compatibility lookup, and frontend fallback removal. No provider request is executed because the retired module intentionally performs no network behavior.