Request Transformation — Complete Gateway Modification Guide

In this tutorial, you will learn about Request Transformation. We cover key concepts, practical examples, and best practices to help you master this topic.

Request transformation allows the API Gateway to modify incoming requests before forwarding them to backend services. This includes adding headers, modifying paths, or transforming request bodies.

What You'll Learn

You'll learn common request transformation patterns including header injection, path rewriting, and body transformation.

Why It Matters

Request transformation enables backward compatibility, protocol translation, and security header injection without modifying backend services.

Real-World Use

A legacy backend expects an API key in a query parameter. The gateway transforms it from a header-based auth to the query parameter format, allowing the frontend to use standard auth patterns while the backend remains unchanged.

Implementation

# Kong request transformer plugin
plugins:
  - name: request-transformer
    config:
      add:
        headers:
          - "X-Request-Id:{uuid}"
          - "X-User-Context:$(headers['X-User-Id'])"
        querystring:
          - "api_version:2.0"
      remove:
        headers:
          - "X-Internal-Token"
      rename:
        headers:
          - "X-Original-URL: X-Forwarded-URL"
      replace:
        body:
          - "old_field_name:new_field_name"

# NGINX request transformation
location /api/v2/ {
    rewrite ^/api/v2/(.*)$ /api/$1 break;
    proxy_pass http://backend:3000;
    proxy_set_header X-API-Version "2.0";
    proxy_set_header X-Original-Method $request_method;
}

Common Mistakes

| Mistake | Fix | |---------|-----| | Overly complex transformations | Keep transformations simple; move logic to services | | Not logging original request | Audit trail lost after transformation | Log both original and transformed request | | Breaking downstream validation | Transformation may invalidate downstream schemas | Coordinate with backend teams | | Unintentional header exposure | Remove sensitive headers before forwarding | | No body size limit | Large body transformations consume memory | Limit body size before processing |

What's Next

Learn about response aggregation in API gateways.