Document updated on Feb 4, 2025
Replace content with regular expressions and other functions
The modifier/response-body
allows you to change the content of any desired fields using several modifiers, from regular expression replacement to simpler modifiers like trimming characters or converting the case.
It works by declaring an array of modifiers
that KrakenD executes sequentially. You can add multiple modifiers to get the desired output.
The modifiers declare an explicit field
where you want to apply the modifications, and the value of these fields must be a string in all cases. If you try to replace content on integers, objects, arrays, etc. the modifier won’t apply any change.
Modifiers can change fields located at the root of the response but also in nested objects. When working with nested objects, the syntax does not allow you to traverse arrays in the path (e.g.: "data": [{"user":"Mary"}]
is not a response a modifier can alter). Still, you can traverse objects (e.g.: "data": {"user":"Larry"}
) with any level of depth you need, using the dot notation. In the latter example, you could have a field: data.user
and modify the Larry
value, but you wouldn’t be able to modify the value of Mary
in the first example.
The modifiers work both in the endpoint
and backend
sections, allowing you to change content before or after the merge operation.
Configuration
The configuration is straightforward and requires you to declare the different modifiers
you want to apply. The modifiers
array declares one modifier per object, and each modifier requires a different set of fields that you can check below.
You will need only one modifier in most cases, but you can add as many as needed. Operations execute sequentially; the one declared at the top of the configuration is the first to apply, and then it moves down. Remember that modifiers skip non-string values.
Here’s a simple example with a single operation to convert to uppercase and lowercase two specific fields:
{
"url_pattern": "/user/{user}",
"extra_config": {
"modifier/response-body": {
"modifiers": [
{
"upper": {
"@comment": "We want all surnames uppercased, like SMITH",
"field": "surname"
}
},
{
"lower": {
"@comment": "We want the address in lower case",
"field": "address"
}
}
]
}
}
}
See the different modifiers you can use below.
Regular expression modifier
The most powerful modifier is the regular expression modifier regexp
that allows you to replace strings using any regular expression you need. It needs the field name where you want to apply the regular expression, the pattern you want to find, and its replacement. Here’s an example:
{
"url_pattern": "/card/{user}",
"extra_config": {
"modifier/response-body": {
"modifiers": [
{
"regexp": {
"@comment": "Ridiculous card masking. Take 4 digits and remove the rest. Credit card is inside a data object.",
"field": "data.credit_card",
"find": "(^\\d{4})(.*)",
"replace": "${1}-XXXX"
}
}
]
}
}
}
Notice that our field
uses the dot .
notation, because we want to modify a nested element, so we have passed data.credit_card
. Then, the find
contains the regular expression, and the replace
is the new output we want to produce. The $1
in the replace references the first capturing group (the 1st parenthesis on find) we have set in the regular expression. This is what the response returns now:
{
"data": {
"credit_card": "1234-XXXX"
}
}
Versus the original response from the backend:
{
"data": {
"credit_card": "1234-56789-1234-5678"
}
}
These are the properties of the modifier:
Configuration of the regexp modifier
modifiers
array- A list of modifiers you would like to apply to specific fields. The modifiers are evaluated and applied in sequential order.Defaults to
[]
Each item of modifiers accepts the following properties:regexp
- A list of regular expressions you would like to apply to specific fields. The expressions are evaluated and applied in sequential order.Example:
[{"field":"data.credit_card","find":"(^\\d{4})(.*)","replace":"${1}-XXXX"}]
field
string- The field you want to modify. The field supports dot notation to access nested objects (it does not work with nested arrays).Example:
"data.credit_card"
find
string- The find expression or literal you want to use. The syntax of the regular expressions accepted is the same general syntax used by Perl, Python, and other languages. More precisely, it is the syntax accepted by RE2 and described at https://golang.org/s/re2syntax
replace
string- The literal string or expression you want to use as a replacement. Use
$
signs to replace captured groups.Example:"${1}-XXXX"
Literal modifier
Replaces in the desired field
a text by another using a literal match (case sensitive). Here’s an example:
{
"url_pattern": "/price",
"extra_config": {
"modifier/response-body": {
"modifiers": [
{
"literal": {
"@comment": "Use the currency name instead of symbol",
"field": "price",
"find": "€",
"replace": "EUR"
}
}
]
}
}
}
Configuration of the literal modifier
modifiers
array- A list of modifiers you would like to apply to specific fields. The modifiers are evaluated and applied in sequential order.Defaults to
[]
Each item of modifiers accepts the following properties:literal
- A literal replacement of strings (case sensitive).Example:
[{"field":"data.example","find":"findme","replace":"replaceme"}]
Uppercase modifier
Replaces a field value with all Unicode letters mapped to their upper case.
{
"url_pattern": "/user",
"extra_config": {
"modifier/response-body": {
"modifiers": [
{
"upper": {
"field": "surname"
}
}
]
}
}
}
Configuration of the upper modifier
modifiers
array- A list of modifiers you would like to apply to specific fields. The modifiers are evaluated and applied in sequential order.Defaults to
[]
Lowercase modifier
Replaces a field value with all Unicode letters mapped to their lower case.
{
"url_pattern": "/user",
"extra_config": {
"modifier/response-body": {
"modifiers": [
{
"lower": {
"field": "surname"
}
}
]
}
}
}
Configuration of the lower modifier
modifiers
array- A list of modifiers you would like to apply to specific fields. The modifiers are evaluated and applied in sequential order.Defaults to
[]
Trim modifier
Removes from a field all characters included in the find
string.
{
"url_pattern": "/hello-world",
"extra_config": {
"modifier/response-body": {
"modifiers": [
{
"trim": {
"field": "message",
"find": "¡!",
"@comments": "Removes exclamation from message, converting '¡¡¡Hello world!!!' to 'Hello world'"
}
}
]
}
}
}
Configuration of the trim modifier
modifiers
array- A list of modifiers you would like to apply to specific fields. The modifiers are evaluated and applied in sequential order.Defaults to
[]
Each item of modifiers accepts the following properties:trim
- Removes a specific set of characters from the beginning and the end of the string.Example:
[{"field":"description","find":"\n"}]
Migration from old plugin
Prior to KrakenD v2.9 part of this functionality was offered through a plugin. Now you can use the native component that offers more functionality and performance without needing to load any plugins.
Here are the changes you would need to do to an existing configuration:
{
"extra_config": {
- "plugin/req-resp-modifier": {
- "name": [
- "content-replacer"
- ],
- "content-replacer": {
- "data.credit_card": {
+ "modifier/response-body": {
+ "modifiers": [
+ {
"@comment": "Ridiculous card masking. Take 4 digits and remove the rest. Credit card is inside a data object.",
+ "field": "data.credit_card",
"find": "(^\\d{4})(.*)",
- "replace": "${1}-XXXX",
- "regexp": true
+ "replace": "${1}-XXXX"
},
- "message": {
+ {
+ "field": "message",
"@comment": "Replace '6 items left' with '6' on the message field",
"find": " items left",
"replace": ""
}
- }
+ ]
}
}
}
The summmary of changes required are:
- Rename the namespace
plugin/req-resp-modifier
tomodifier/response-body
- Remove the
name
property - Rename
content-replacer
tomodifiers
and instead of an object convert it into an array - For each key you had, create an object using one of the available modifiers
- If this was the last
plugin/xxx
entry in your configuration, remove the configuration blockplugin
at the root of the configuration
If you have doubts, please get in touch with support.
