Request & Response Transformation

Header Manipulation

The most common transformation. Add, remove, or rename headers before forwarding:

location /api/ {
    proxy_pass http://notes;

    # Add headers to backend request
    proxy_set_header X-Request-ID   $request_id;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP       $remote_addr;

    # Remove headers from client request before forwarding
    proxy_set_header Authorization "";  # backend doesn't need raw JWT

    # Remove headers from backend response before returning to client
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;

    # Add headers to the response
    add_header X-Gateway-Version "1.0";
    add_header Strict-Transport-Security "max-age=31536000";
}

In Node.js middleware:

function transformRequest(req: Request, _res: Response, next: NextFunction): void {
  // Enrich with request ID for distributed tracing
  req.headers['x-request-id'] = req.headers['x-request-id'] ?? crypto.randomUUID();
  req.headers['x-forwarded-for'] = req.socket.remoteAddress;

  // Strip sensitive client headers
  delete req.headers['authorization']; // replaced by x-user-id from auth middleware
  delete req.headers['cookie'];        // don't forward cookies to APIs

  next();
}

function transformResponse(req: Request, res: Response, next: NextFunction): void {
  // Remove internal headers from response
  res.on('finish', () => {
    res.removeHeader('x-powered-by');
    res.removeHeader('x-internal-service');
  });
  next();
}

Path Rewriting

Map external paths to internal paths. Clients use clean URLs; backends use whatever they want:

# Strip /api/v1 prefix before forwarding
location /api/v1/users/ {
    rewrite ^/api/v1/(.*)$ /$1 break;
    proxy_pass http://user-service;
}
# GET /api/v1/users/123 → GET /users/123 on user-service

// In Express gateway
app.use('/api/v1/users', (req, res, next) => {
  // Rewrite path: /api/v1/users/123 → /123
  req.url = req.url.replace(/^\/api\/v1\/users/, '');
  proxy.web(req, res, { target: 'http://user-service:3001' });
});

Payload Transformation

Reshape request or response bodies. Useful when migrating API versions or integrating third-party services with mismatched schemas:

// v1 clients send snake_case; new backend expects camelCase
function transformV1Request(body: Record<string, unknown>): Record<string, unknown> {
  return {
    userId:    body.user_id,
    firstName: body.first_name,
    lastName:  body.last_name,
    emailAddr: body.email_address,
  };
}

// Middleware that transforms request body
app.use('/api/v1/', async (req, res, next) => {
  if (req.method !== 'GET' && req.body) {
    req.body = transformV1Request(req.body);
  }
  next();
});

Response transformation — adapt backend response before returning to client:

function transformUserResponse(backendResponse: BackendUser): ClientUser {
  return {
    id:         backendResponse.userId,
    first_name: backendResponse.firstName, // client expects snake_case
    last_name:  backendResponse.lastName,
    email:      backendResponse.emailAddr,
    // Strip internal fields
    // (no: internalFlags, createdBySystem, etc.)
  };
}

API Versioning at the Gateway

Keep old API versions alive without maintaining old code in services:

// Route v1 and v2 to different backends
const versionRoutes = {
  'v1': 'http://api-v1:3000',
  'v2': 'http://api-v2:3000',
};

// Version from URL: /api/v1/users
app.use('/api/:version/*', (req, res) => {
  const version = req.params.version;
  const target = versionRoutes[version];

  if (!target) {
    return res.status(404).json({ error: `API version ${version} not found` });
  }

  proxy.web(req, res, { target });
});

// Version from header: X-API-Version: 2
app.use('/api/', (req, res) => {
  const version = req.headers['x-api-version'] ?? 'v1';
  proxy.web(req, res, { target: versionRoutes[version] });
});

Deprecation notices:

function addDeprecationHeaders(req: Request, res: Response, next: NextFunction): void {
  if (req.path.startsWith('/api/v1')) {
    res.set('Deprecation', 'true');
    res.set('Sunset', 'Sat, 31 Dec 2026 23:59:59 GMT');
    res.set('Link', '</api/v2>; rel="successor-version"');
  }
  next();
}

Protocol Translation

Convert between protocols at the gateway — clients speak REST, backends speak gRPC:

import * as grpc from '@grpc/grpc-js';

// Gateway translates REST → gRPC
app.get('/api/users/:id', async (req, res) => {
  const client = new UserServiceClient(
    'user-service:50051',
    grpc.credentials.createInsecure(),
  );

  // REST request → gRPC call
  client.getUser({ userId: req.params.id }, (err, response) => {
    if (err) {
      return res.status(503).json({ error: 'Service unavailable' });
    }

    // gRPC response → REST JSON response
    res.json({
      id:    response.userId,
      name:  response.name,
      email: response.email,
    });
  });
});

This lets you migrate backends to gRPC incrementally while clients keep using REST.

Kong Transformation Plugins

plugins:
  # Add/remove/rename headers
  - name: request-transformer
    config:
      add:
        headers:
          - "x-request-source:gateway"
      remove:
        headers:
          - authorization
      rename:
        headers:
          - "x-custom-id:x-user-id"

  # Rewrite path
  - name: request-transformer
    config:
      replace:
        uri: "/$(uri_captures.version)/$(uri_captures.path)"

  # Response transformation
  - name: response-transformer
    config:
      remove:
        headers:
          - x-powered-by
          - server