Transformation Workflow (XML ↔ JSON)¶

Overview¶

The Transformation Workflow feature in Yappes enables API-level transformation between XML and JSON formats without modifying backend or client applications.

This capability allows organizations to:

Convert XML requests to JSON for modern backend services.
Convert JSON requests to XML for legacy systems.
Transform responses bidirectionally.
Standardize payload formats across APIs.

Why This Matters¶

Bridge legacy XML services with modern JSON clients.
Reduce custom integration code.
Centralize transformation logic at the gateway.
Improve developer experience.
Support compliance and standardization initiatives.

Scope¶

XML → JSON transformation.
JSON → XML transformation.
Request and response handling.
Policy attachment at the API level.
Gateway-level enforcement.
Test configuration before deployment.

Outcome¶

Faster integrations.
Reduced implementation cost.
Secure and controlled mediation.
Consistent API behavior.

When to Use Transformation Workflow¶

Use this feature when:

Legacy backend systems accept only XML, but clients send JSON.
Backend services return XML, but consumers expect JSON.
You need centralized format mediation.
You want to standardize payload formats across APIs.
You want to avoid modifying backend services.

When Not to Use Transformation Workflow¶

Do not use this feature when:

The backend already supports both XML and JSON natively.
The transformation requires complex business logic beyond structural conversion.
Payload transformation involves data enrichment or external lookups.
Schema mapping requires conditional or dynamic rule engines.

Prerequisites¶

Required Access and Permissions¶

Users must have:

API Manager access.
Permission to create Transformation Workflows.
Permission to modify APIs.
Permission to attach policies.

System / Technical Requirements¶

A valid XML schema (for XML → JSON transformation).
A valid JSON structure (for JSON → XML transformation).
Well-formed payload samples.
Browser access to Yappes API Manager.
An API deployed in the “My APIs” section.

Transformation Workflow Features¶

Under the Transformation Workflow section, the user can:

Create Transformation Workflow: Create a new transformation workflow for XML to JSON or JSON to XML conversion.
Attach/Detach Workflow: Attach or detach a transformation workflow at the API or Endpoint level.
Search Workflow: Search for transformation workflows using the workflow name.
Filter by Type: Filter workflows based on transformation type (XML to JSON / JSON to XML).
View Workflow: View the configuration of an existing transformation workflow.
Edit Workflow: Modify the configuration of an existing transformation workflow.
Delete Workflow: Permanently remove a transformation workflow from the system.
Check Linked APIs/Endpoints: View how many APIs or Endpoints are associated with a particular workflow.

Step-by-Step Implementation¶

Method 1: Creating Transformation Workflow from Transformation Workflow Section¶

Step 1: Navigate to Transformation Workflow Section¶

From the left navigation panel, open Bridge.
Select Transformation Workflow.
Select Create Transformation Workflow.

Method 1.1: Create XML → JSON Transformation Workflow¶

Step 2: Define Workflow Details¶

Enter a unique name in the Transformation Name * field.
Provide a description in the Description field.
Select the Transformation Type * (Request or Response).
Open the Transformation Format * dropdown.
Select XML to JSON.

Step 3: Configure Schema¶

Enter the XML schema inside the Paste or edit schema here... field.
Define or paste the XML schema structure.
Select Test Configuration.
Review the transformed JSON output.
Close the test window.

Method 1.2: Create JSON → XML Transformation Workflow¶

Step 4: Change Transformation Format¶

Open the Transformation Format * dropdown.
Select JSON to XML.

Step 5: Configure JSON to XML Schema¶

Enter the JSON structure inside the Paste or edit schema here... field.
Paste the JSON structure to be converted.
Select Test Configuration.
Review the transformed XML output.
Close the test window.

Step 6: Create the Workflow¶

Review all entered details and configurations.
Click Create Transformation.

Attaching or Detaching a Workflow¶

After you create a transformation workflow, attach it to API endpoints so the gateway applies the conversion. You can also detach it from endpoints that no longer need it.

Policies are linked at Endpoint Level.

Steps to attach a workflow¶

From Bridge → Transformation Workflow, open the workflow list.
In the Attach or Detach column for the workflow, click Attach or Detach.
In the Attach/Detach Transformation workflow window, under Attach or Detach workflow, select Attach Policy.
Optionally use Search by API name or Endpoint name to find targets.
Select the endpoints to attach, then click Attach.

Steps to detach a workflow¶

From Bridge → Transformation Workflow, open the workflow list.
In the Attach or Detach column for the workflow, click Attach or Detach.
In the Attach/Detach Transformation workflow window, under Attach or Detach workflow, select Detach Policy.
Optionally search, then select the endpoints to detach and click Detach.

Note

Attachment follows these rules:

Workflows attach at endpoint level only.
For a Request transformation, GET endpoints cannot be selected (GET cannot be selected in the list).
For a JSON to XML workflow, SOAP APIs are not listed as attach targets.

Understanding the Interface¶

Section	Purpose
Bridge	Contains mediation and transformation tools.
Transformation Workflow	Manage XML ↔ JSON workflows.
Create Transformation Workflow	Define a new transformation policy.
Test Configuration	Validate the schema before saving.
My APIs	Manage and configure APIs.
Attach Policy	Attach the transformation workflow to an API.

Configuration and Settings¶

Required Configuration Fields¶

Field	Mandatory	Description
Transformation Name	Yes	Unique workflow identifier.
Description	Yes	Purpose of the transformation.
Transformation Type	Yes	Request or Response transformation direction.
Transformation Format	Yes	XML to JSON or JSON to XML conversion.
Schema Configuration	Yes	Structure definition used for the transformation.

Key Configuration Requirements¶

Schema must be syntactically valid.
XML must be well-formed.
JSON must be properly structured.
Transformation name must be unique.
Large payload structures should be tested before deployment.

Best Practices for Configuration¶

Practice	Reason
Test configuration before saving	Prevent runtime errors.
Use descriptive names	Easier governance.
Validate sample payloads	Avoid deployment issues.
Version control workflows	Safer change management.
Attach only to required APIs	Limit unnecessary processing.

What Happens If Validation Fails¶

If configuration validation fails:

The workflow cannot be created.
Schema errors are displayed in the test panel.
API attachment will not proceed.
The gateway will not enforce invalid configurations.

At runtime:

An invalid payload format results in transformation failure.
The client may receive an error response.
Failure events are logged for monitoring.

Example Requests¶

Valid Example (XML → JSON)¶

Input (XML):

<order>
  <id>1001</id>
  <customer>John</customer>
</order>

Output (JSON):

{
  "order": {
    "id": "1001",
    "customer": "John"
  }
}

Invalid Example¶

Malformed XML:

<order>
  <id>1001</id>
  <customer>John
</order>

❌ Fails because XML is not well-formed.

Policy Evaluation Order¶

Request enters the Gateway.
Security policies execute (Authentication, Authorization).
Transformation Workflow executes.
The request is forwarded to the backend.
Response transformation is applied (if configured).
The response is returned to the client.

Short-circuit behavior¶

If validation fails, the transformation does not execute.
The Gateway returns an error before backend invocation.

Verification and Testing¶

To confirm functionality:

Send an XML payload to an API expecting a JSON backend.
Verify that the backend receives JSON.
Send a JSON payload to an API expecting an XML backend.
Verify that the backend receives XML.
Confirm that response transformation occurs correctly.

Success Indicators¶

No schema errors.
Correct format conversion.
No gateway errors.
Successful backend processing.

Troubleshooting¶

Issue	Possible Cause	Resolution
Transformation not applied	Workflow not attached	Reattach the workflow and save the API.
Test Configuration fails	Invalid schema	Correct the syntax and retest.
API returns format error	Payload mismatch	Validate the client request format.
Changes not reflected	API not saved	Click Save after attaching the policy.

Best Practices¶

Always test before production deployment.
Use versioned workflow names.
Avoid large structural changes in production.
Validate payload size impact.
Document transformation logic internally.

❓ Frequently Asked Questions¶

Does this modify backend services?
No. Transformation occurs at the gateway.

Can I attach multiple transformation workflows?
Attach only the required workflow per API to avoid conflicts.

Is transformation applied to both request and response?
Yes. It is applied based on the configured transformation type.

Does this affect performance?
There is minimal overhead, but large payloads should be tested.

Impact of Policy Changes¶

Changing the schema affects all APIs using that workflow.
Removing a workflow may break client compatibility.
Always validate changes in staging before production deployment.
Rollback requires reattaching the previous workflow version.

Pro Tip

Use Transformation Workflow to centrally manage XML ↔ JSON payload conversions at the Yappes gateway. This approach eliminates the need to modify backend services or client applications while maintaining consistent API behavior across integrations.