Реализация трансформации запросов/ответов на API Gateway

Реализация трансформации запросов/ответов на API Gateway

Трансформация на уровне Gateway позволяет адаптировать формат данных между клиентом и сервисом без изменения кода самих сервисов. Типичные задачи: переименование полей, фильтрация чувствительных данных, добавление системных заголовков, версионирование без переписывания API.

Трансформация в Kong (Request/Response Transformer)

# Трансформация запроса
curl -X POST http://localhost:8001/services/users-api/plugins \
  -d "name=request-transformer" \
  -d "config.add.headers[]=X-Service-Version:1.2.3" \
  -d "config.add.headers[]=X-Request-ID:$(uuidgen)" \
  -d "config.remove.headers[]=X-Real-IP" \
  -d "config.rename.headers[]=Authorization:X-Auth-Token" \
  -d "config.add.querystring[]=format:json"

# Трансформация ответа
curl -X POST http://localhost:8001/services/users-api/plugins \
  -d "name=response-transformer" \
  -d "config.remove.headers[]=X-Internal-Server" \
  -d "config.remove.headers[]=X-Powered-By" \
  -d "config.remove.headers[]=Server" \
  -d "config.add.headers[]=Cache-Control:no-store" \
  -d "config.add.headers[]=X-Content-Type-Options:nosniff"

Трансформация тела запроса (JSON):

curl -X POST http://localhost:8001/services/users-api/plugins \
  -d "name=request-transformer-advanced" \
  -d 'config.add.body[]=source:web' \
  -d 'config.remove.body[]=internal_debug_flag' \
  -d 'config.rename.body[]=user_id:userId'  # camelCase для старого сервиса

Трансформация в APISIX (proxy-rewrite + response-rewrite)

{
  "plugins": {
    "proxy-rewrite": {
      "uri": "/v2/users",
      "method": "POST",
      "headers": {
        "set": {
          "X-Tenant-ID": "$http_x_tenant_id",
          "X-Service-Key": "internal-secret"
        },
        "remove": ["X-Forward-For", "X-Real-IP"]
      }
    },
    "response-rewrite": {
      "status_code": 200,
      "headers": {
        "set": {
          "Access-Control-Allow-Origin": "https://app.company.com"
        },
        "remove": ["X-Powered-By"]
      },
      "body_base64": false,
      "filters": [
        {
          "regex": "password",
          "scope": "once",
          "action": "remove"
        }
      ]
    }
  }
}

Трансформация в AWS API Gateway (Velocity Templates)

## Маппинг входящего запроса
#set($inputRoot = $input.path('$'))
{
  "userId": "$context.authorizer.user_id",
  "tenantId": "$context.authorizer.tenant_id",
  "data": {
    "email": "$inputRoot.email",
    "name": "$inputRoot.name"
  },
  "metadata": {
    "ip": "$context.identity.sourceIp",
    "userAgent": "$context.identity.userAgent",
    "requestId": "$context.requestId"
  }
}

Трансформация ответа (убрать вложенность):

## Integration Response mapping template
#set($inputRoot = $input.path('$.data'))
{
  "id": "$inputRoot.id",
  "email": "$inputRoot.email",
  "name": "$inputRoot.name",
  "createdAt": "$inputRoot.created_at"
}

Фильтрация чувствительных полей в ответе

-- Kong плагин: удаление полей перед отправкой клиенту
local function filter_response(body_json)
  local sensitive = {"password_hash", "secret_key", "internal_id", "admin_notes"}
  for _, field in ipairs(sensitive) do
    body_json[field] = nil
  end
  return body_json
end

-- В плагине header_filter/body_filter
local body = cjson.decode(ngx.arg[1])
ngx.arg[1] = cjson.encode(filter_response(body))

Версионирование через трансформацию

Старый клиент (v1 API) → Gateway адаптирует к v2 формату сервиса:

// KrakenD serverless middleware
var adaptV1toV2 = new TykJS.TykMiddleware.NewMiddleware({})

adaptV1toV2.NewProcessRequest(function(request, session) {
  var body = JSON.parse(request.Body)

  // Клиент присылает v1 формат: { "user_id": 123 }
  // Сервис ожидает v2 формат: { "userId": "123", "version": 2 }
  var transformed = {
    userId: String(body.user_id),
    version: 2
  }

  request.Body = JSON.stringify(transformed)
  return TykJS.TykMiddleware.ReturnData(request, {})
})

Protocol transformation: REST → GraphQL

KrakenD поддерживает GraphQL backend из REST клиентского запроса:

{
  "endpoint": "/api/v1/user/{id}",
  "backend": [
    {
      "url_pattern": "/graphql",
      "host": ["http://graphql-service:4000"],
      "extra_config": {
        "backend/graphql": {
          "type": "query",
          "query": "query GetUser($id: ID!) { user(id: $id) { id name email } }",
          "variables": {
            "id": "{id}"
          }
        }
      }
    }
  ]
}

XML ↔ JSON конвертация

# APISIX: конвертация XML ответа в JSON
plugins:
  xml-json:
    trim_space: true
    cdata_to_json: false
    omit_xml_declaration: false

Срок выполнения

Настройка трансформации запросов/ответов (заголовки, тело, фильтрация полей) — 1–2 рабочих дня.