Configuring Request Transformation
1. Transforming Request Headers
| Operation | Example |
|---|---|
| Add | X-Internal-Auth: secret |
| Remove | Strip X-Forwarded-Host |
| Rename | X-Api-Key → X-Internal-Key |
| Replace | Overwrite if present |
| Append | Multi-value header |
Example: Kong request-transformer
plugins:
- name: request-transformer
config:
add:
headers: ["X-Internal-Trace:$(uuid)", "X-Source:gateway"]
remove:
headers: ["X-Debug-Token"]
rename:
headers: ["X-Old-Auth:X-New-Auth"]2. Using Path Rewriting Rules
Example: Strip prefix, rewrite
location /api/v1/ {
rewrite ^/api/v1/(.*)$ /$1 break;
proxy_pass http://backend;
}
# /api/v1/users → backend/users| Directive | Effect |
|---|---|
strip_path | Remove matched prefix |
rewrite regex | Pattern substitution |
prefix_rewrite | Replace start of path |
3. Implementing Query Parameter Transformation
| Op | Example |
|---|---|
| Add | ?tenant=acme |
| Remove | Strip ?debug |
| Rename | page → offset |
| Transform | Page number → offset math |
4. Modifying Request Body
Example: JSON body enrichment
local cjson = require "cjson"
local body = cjson.decode(kong.request.get_raw_body())
body.tenant_id = kong.ctx.shared.tenant
body.received_at = ngx.now()
kong.service.request.set_raw_body(cjson.encode(body))5. Converting Request Methods
| From | To | Use Case |
|---|---|---|
| POST | PUT | Legacy client compat |
GET ?_method=DELETE | DELETE | Firewall restrictions |
| PATCH | PUT | Backend doesn't support PATCH |
6. Setting Default Request Values
Example: Default query and body
plugins:
- name: request-transformer
config:
add:
querystring: ["page=1", "limit=20"]
body: ["source=api-gateway"]7. Using Template-Based Transformation
| Template Engine | Syntax |
|---|---|
| Mustache | {{ headers.host }} |
| Jinja2 | {% if ... %} |
| Envoy CEL | request.headers["x-id"] |
| JSONata | Functional JSON transform |
8. Implementing Request Enrichment
Example: Inject user context from JWT
local jwt = kong.ctx.shared.jwt_payload
kong.service.request.set_header("X-User-Id", jwt.sub)
kong.service.request.set_header("X-User-Roles", table.concat(jwt.roles, ","))
kong.service.request.set_header("X-Tenant-Id", jwt.tenant)9. Configuring Content Encoding
| Encoding | When |
|---|---|
| gzip on upload | Reduce bandwidth |
| Decode for inspection | WAF body scan |
| Re-encode for backend | Backend wants raw |
10. Setting Up Request Mapping Rules
| Mapping | Example |
|---|---|
| Header → Query | X-Region → ?region= |
| JWT claim → Header | sub → X-User-Id |
| Path param → Body | /users/:id → {"id":...} |
| Query → Body | For GET-to-POST conversion |