ARCHIVED from builddistributedsystem.com on 2026-04-28 — URL: https://builddistributedsystem.com/tracks/proxies/tasks/task-21-2-3-transformation
TASK

Implementation

API gateways transform requests and responses to bridge the gap between client expectations and backend implementations. This enables legacy integration and protocol translation.

Transformation types:

1. Format transformation:
   Client (JSON) → Gateway → Backend (XML)

2. Protocol translation:
   Client (REST) → Gateway → Backend (gRPC)

3. Field mapping:
   Client (userId) → Gateway → Backend (user_id)

4. Aggregation:
   Client → Gateway → [Backend A, Backend B] → Gateway → Client

Example: JSON to XML transformation:

// Client sends JSON:
Request:  {"type": "api_request", "msg_id": 1, "method": "POST", "path": "/api/users", "headers": {"Content-Type": "application/json"}, "body": {"name": "Alice", "email": "alice@example.com"}}

// Gateway transforms to XML and sends to backend:
Backend Request:  {"method": "POST", "path": "/users", "headers": {"Content-Type": "application/xml"}, "body": "<?xml version="1.0"?><user><name>Alice</name><email>alice@example.com</email></user>"}

// Backend responds with XML:
Backend Response:  {"status": 201, "body": "<?xml version="1.0"?><user><id>123</id><name>Alice</name><email>alice@example.com</email></user>"}

// Gateway transforms to JSON and sends to client:
Response: {"type": "api_response", "in_reply_to": 1, "status": 201, "body": {"id": 123, "name": "Alice", "email": "alice@example.com"}}

Field mapping configuration:

{
  "transformations": {
    "/api/users": {
      "request": {
        "field_mappings": {
          "userId": "user_id",
          "firstName": "first_name",
          "lastName": "last_name"
        },
        "format": "json_to_xml"
      },
      "response": {
        "field_mappings": {
          "user_id": "userId",
          "first_name": "firstName",
          "last_name": "lastName"
        },
        "format": "xml_to_json"
      }
    }
  }
}

Sample Test Cases

JSON to XML transformationTimeout: 5000ms
Input
{"src":"client","dest":"gateway","body":{"type":"init","msg_id":1,"transformations":{"/api/users":{"request":{"format":"json_to_xml"},"response":{"format":"xml_to_json"}}}}}
{"src":"client","dest":"gateway","body":{"type":"api_request","msg_id":2,"method":"POST","path":"/api/users","body":{"name":"Alice"}}}
Expected Output
{"src": "gateway", "dest": "client", "body": {"type": "init_ok", "in_reply_to": 1}}
Field mappingTimeout: 5000ms
Input
{
  "src": "client",
  "dest": "gateway",
  "body": {
    "type": "api_request",
    "msg_id": 1,
    "method": "POST",
    "path": "/api/users",
    "body": {
      "userId": "user123",
      "firstName": "Alice"
    }
  }
}
Expected Output
{"src": "gateway", "dest": "client", "body": {"type": "api_response", "in_reply_to": 1, "body": {"userId": "user123", "firstName": "Alice"}}}

Hints

Hint 1
Transform request format before sending to backend (e.g., JSON → XML)
Hint 2
Transform response format before returning to client (e.g., XML → JSON)
Hint 3
Protocol translation: REST → gRPC, GraphQL → REST
Hint 4
Legacy integration: modern JSON clients → legacy XML backends
Hint 5
Field mapping: rename fields between client and backend schemas
OVERVIEW

Theoretical Hub

Concept overview coming soon

Key Concepts

request transformationresponse transformationprotocol translationformat conversionlegacy integration
main.py
python
Implement Request/Response Transformation - Proxies | Build Distributed Systems