This plugin transforms the request sent by a client on the fly on Kong, before hitting the upstream server. It can match complete or portions of incoming requests using regular expressions, save those matched strings into variables, and substitute those strings into transformed requests via flexible templates.

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=request-transformer"

service: the id or name of the Service that this plugin configuration will target.

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=request-transformer"

route_id: the id of the Route that this plugin configuration will target.

You can use the http://localhost:8001/plugins endpoint to enable this plugin on specific Consumers:

$ curl -X POST http://kong:8001/plugins \
    --data "name=request-transformer" \
    --data "consumer_id={consumer_id}"

Where consumer_id is the id of the Consumer we want to associate with this plugin.

You can combine consumer_id and service_id in the same request, to furthermore narrow the scope of the plugin.

Notes:

• If the value contains a , then the comma-separated format for lists cannot be used. The array notation must be used instead.
• The X-Forwarded-* fields are non-standard header fields written by Nginx to inform the upstream about client details and can't be overwritten by this plugin. If you need to overwrite these header fields, see the post-function plugin in Serverless Functions.

You can use any of the current request headers, query params, and captured URI groups as a template to populate the above supported configuration fields.

To escape a template, wrap it inside quotes and pass it inside another template.
$('$(some_escaped_template)')

Note: The plugin creates a non-mutable table of request headers, querystrings, and captured URIs before transformation. Therefore, any update or removal of params used in template does not affect the rendered value of a template.

The content of the placeholder $(...) is evaluated as a Lua expression, so logical operators may be used. For example:

Header-Name:$(uri_captures["user-id"] or query_params["user"] or "unknown")

This will first look for the path parameter (uri_captures). If not found, it will return the query parameter. If that also doesn't exist, it returns the default value '"unknown"'.

Constant parts can be specified as part of the template outside the dynamic placeholders. For example, creating a basic-auth header from a query parameter called auth that only contains the base64-encoded part:

Authorization:Basic $(query_params["auth"])

Lambdas are also supported if wrapped as an expression like this:

$((function() ... implementation here ... end)())

A complete Lambda example for prefixing a header value with "Basic" if not already there:

Authorization:$((function()
    local value = headers.Authorization
    if not value then
      return
    end
    if value:sub(1, 6) == "Basic " then
      return value            -- was already properly formed
    end
    return "Basic " .. value  -- added proper prefix
  end)())

NOTE: Especially in multi-line templates like the example above, make sure not to add any trailing white-space or new-lines. Because these would be outside the placeholders, they would be considered part of the template, and hence would be appended to the generated value.

The environment is sandboxed, meaning that Lambdas will not have access to any library functions, except for the string methods (like sub() in the example above).

Add an API test with uris configured with a named capture group user_id

$ curl -X POST http://localhost:8001/apis \
    --data 'name=test' \
    --data 'upstream_url=http://mockbin.com' \
    --data-urlencode 'uris=/requests/user/(?<user_id>\w+)' \
    --data "strip_uri=false"

Enable the ‘request-transformer’ plugin to add a new header x-consumer-id whose value is being set with the value sent with header x-user-id or with the default value alice is header is missing.

$ curl -X POST http://localhost:8001/apis/test/plugins \
    --data "name=request-transformer" \
    --data-urlencode "config.add.headers=x-consumer-id:\$(headers['x-user-id'] or 'alice')" \
    --data "config.remove.headers=x-user-id"

Now send a request without setting header x-user-id

$ curl -i -X GET localhost:8000/requests/user/foo

Plugin will add a new header x-consumer-id with value alice before proxying request upstream. Now try sending request with header x-user-id set

$ curl -i -X GET localhost:8000/requests/user/foo \
  -H "X-User-Id:bob"

This time the plugin will add a new header x-consumer-id with the value sent along with the header x-user-id, i.e.bob

Plugin performs the response transformation in the following order:

• remove → rename → replace → add → append

In these examples we have the plugin enabled on a Service. This would work similarly for Routes.

• Add multiple headers by passing each header:value pair separately:

With a database

$ curl -X POST http://localhost:8001/services/example-service/plugins \
  --data "name=request-transformer" \
  --data "config.add.headers[1]=h1:v1" \
  --data "config.add.headers[2]=h2:v1"

** Without a database **

plugins:
- name: request-transformer
  config:
    add:
      headers: ["h1:v1", "h2:v1"]

• Add multiple headers by passing comma separated header:value pair (only possible with a database):

$ curl -X POST http://localhost:8001/services/example-service/plugins \
  --data "name=request-transformer" \
  --data "config.add.headers=h1:v1,h2:v2"

• Add multiple headers passing config as JSON body (only possible with a database):

$ curl -X POST http://localhost:8001/services/example-service/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "request-transformer", "config": {"add": {"headers": ["h1:v2", "h2:v1"]}}}'

• Add a querystring and a header:

** With a database **

$ curl -X POST http://localhost:8001/services/example-service/plugins \
  --data "name=request-transformer" \
  --data "config.add.querystring=q1:v2,q2:v1" \
  --data "config.add.headers=h1:v1"

** Without a database **

plugins:
- name: request-transformer
  config:
    add:
      headers: ["h1:v1"],
      querystring: ["q1:v1", "q2:v2"]

• Append multiple headers and remove a body parameter:

** With a database **

$ curl -X POST http://localhost:8001/services/example-service/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "request-transformer", "config": {"append": {"headers": ["h1:v2", "h2:v1"]}, "remove": {"body": ["p1"]}}}'

** Without a database **

plugins:
- name: request-transformer
  config:
    add:
      headers: ["h1:v1", "h2:v1"]
    remove:
      body: [ "p1" ]