Kong is so powerful and flexible because of its plugins. When users are designing their APIs, sometimes transforming the request is inevitable. Request Transformer Advanced plugin comes in very handy in such situation. In this article I will try my best to explain what you can do with this plugin. As it is a complicated plugin, I will only cover a few examples, users need to decide what they want to do with it.
What can be transform?
Please see below table of what can be transformed. Let’s say if you want to add a header, when you are enabling this plugin on a route, service or globally, you need to add the new header to config.add.headers parameter.
headers
body
querystring
uri
http_method
add
add
add
remove
remove
remove
replace
replace
replace
replace
rename
rename
rename
append
append
append
allow
Preparation
Let me start with some examples. I will be using Admin API to set up.
For the advanced usage, I will cover how to use build in variables as well as Lua code to transform requests.
Template as Value
There are 3 sandboxed variables that we can use to make this plugin more useful.
headers
query_params
uri_captures
Official documentation gave us some use case, let me use one of them as an example.
1 2 3
curl -X POST 'http://localhost:8001/plugins' \ -d 'name=request-transformer-advanced' \ -d 'config.add.headers=Class:$(query_params["category"] or headers["category"] or "standard")'
In this example we will add a Class header to the request. The value of this header comes from another header or query string category. If there is no such header or querystring, we use standard to Class header.
Please note this feature is turned off by default if you are using Kong 2.2.x or later. Please check changelog for more information.
I have set KONG_UNTRUSTED_LUA=on for the demonstration purpose.
If you want to go further and use logical operations to transform the requests, you can write some simple Lua code as advanced templates. Here is one use case.
Let’s say you want to add a header called Country based on the query string brand passed in.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
curl -X POST 'http://localhost:8001/plugins' \ -d 'name=request-transformer-advanced' \ -d 'config.add.headers=Country:$((function() local value = query_params.brand if not value then return "Unknown" end value = value:lower() if value == "telstra" then return "Australia" elseif value == "bmw" then return "Germany" else return "Unknown" end end)())'
Now when I run curl 'http://localhost:8000/request?brand=telstra', you can see the Country header is added with Australia as its value.
Kong supports regular expression pattern matching for an Route’s paths field. These Regex match group can be captured and used in Request Transformation plugin as well.
Now when we access the route at curl 'http://localhost:8000/myapi/v2/user/123456/test', we should get below response. As we can see "api": "v2" and "user": "123456" were sent to upstream.
_format_version:"2.1" _transform:true services: -name:request-service url:https://httpbin.org/anything routes: -name:request-route paths: -/request plugins: -name:request-transformer-advanced route:request-route config: add: headers: -|- Country:$((function() local value = query_params.brand if not value then return "Unknown" end value = value:lower() if value == "telstra" then return "Australia" elseif value == "bmw" then return "Germany" else return "Unknown" end end)())
Kubernetes Ingress Controller
You can also applied this plugin with Kong Ingress Controller.
Below example will deploy:
Echo deployment
Echo Service
Request Transformer Advanced plugin with advanced template
Ingress rule to use this plugin
Please save below to request.yaml and then kubectl apply -f request.yaml to apply it.