Response Transformer

Overview

The Response Transformer policy is an outbound policy, and it modifies the response returned from the upstream service before delivering it to the client. This transformation allows for:

• Adding, removing, replacing, renaming, or appending response headers or JSON fields.
• Filtering or restructuring response bodies.
• Masking or transforming sensitive fields.
• Ensuring consistency of response payloads across different services.

This is especially useful when you want to hide internal implementation details or align API responses with external client contracts.

note

This plugin is compatible with DB-less mode and supports grpc, grpcs, http, and https protocols.

Configuration Details

The configuration uses a simple key-value format for declaring transformation operations. Each operation is defined under a specific namespace and supports both headers and JSON body fields.

Transformation Order

Transformations execute in the following order:

1. Remove
2. Rename
3. Replace
4. Add
5. Append

Supported Transformation Fields

Field	Description
remove	Remove specific response headers or JSON keys
rename	Rename existing response headers or JSON keys
replace	Replace values of existing response headers or JSON keys
add	Add new response headers or JSON fields (replaces existing fields if already present)
append	Append additional values to existing headers or JSON arrays

Key Configuration Options

Field	Description
config.add.headers	Add new response headers. Format: header-name:value
config.add.json	Add new JSON keys to the response body. Format: key:value
config.add.json_types	Explicitly set JSON value types (string, boolean, number) when using add or append.
config.append.headers	Append values to existing headers. Format: header-name:value
config.append.json	Append values to existing JSON keys.
config.remove.headers	Remove existing response headers. Format: header-name
config.remove.json	Remove specific JSON keys from the response.
config.rename.headers	Rename headers. Format: old-name:new-name
config.rename.json	Rename JSON keys. Format: old-key:new-key
config.replace.headers	Replace header values. Format: header-name:new-value
config.replace.json	Replace JSON key values. Format: key:new-value
config.replace.json_types	Required when replacing JSON values with non-string types (boolean, number).

Examples

Basic Example - Add Headers and JSON Keys

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"add": {
				"headers": ["x-new-header:value", "x-another-header:something"],
				"json": ["new-json-key:some_value", "another-json-key:some_value"],
				"json_types": ["string", "boolean", "number"]
		}
	}
}'

Append Headers and Remove JSON Field

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"append": {
				"headers": ["x-header-1:v2", "x-header-2:v1"]
			},
			"remove": {
				"json": ["internal-field"]
		}
	}
}'

Rename JSON Key and Header

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--data "name=response-transformer" \
	--data "config.rename.headers=old-header:new-header" \
	--data "config.rename.json=old-key:new-key"

Full Example with Multiple Actions

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"remove": {
				"headers": ["x-toremove", "x-another-one"],
				"json": ["json-key-toremove", "another-json-key"]
		},
		"add": {
			"headers": ["x-new-header:value"],
			"json": ["new-json-key:some_value"],
			"json_types": ["string"]
		},
		"append": {
			"headers": ["x-existing-header:some_value", "x-another-header:some_value"]
		}
	}
}'

Additional Notes

• If a value contains a comma (,), the array notation must be used (e.g., JSON array).
• This plugin retains the entire response body in memory during transformation, which may impact performance on large responses.
• When transforming gzip-compressed payloads, ensure the Content-Encoding: gzip header is properly handled.
• This plugin does not modify x-forwarded-* headers written by Nginx.
• JSON key value types (json_types) are critical when appending or adding numeric or boolean fields.

For more instructions and advanced examples of using the policy, please refer to this guide: Response Transformer - Plugin | Kong Docs