Document updated on Oct 25, 2022

Response manipulation with query language (JMESPath)

If you’d like to apply advanced manipulations before you return the API data, the modifier/jmespath allows you to apply JSON query language expressions. Fine-tune the final content delivered to the user, and even add the possibility to add small logic chunks.

The JMESPath query language allows you to select, slice, filter, map, project, flatten, sort, and all sorts of operations. To get familiar with the language, we recommend reading the JMESPath Tutorial and the JMESPath examples.

Let’s better illustrate the query language with an example. Your backend returns the following content:

{
  "students": [
    {"name": "Bill", "age": 23 },
    {"name": "Mary", "age": 16 },
    {"name": "Jessica", "age": 19 }
  ]
}

But you only need the names of those students who are over 18. You could apply an expression like this:

students[?age > `18` ].name

And the final output would be:

["Bill", "Jessica"]

How JMESPath works

After KrakenD has fetched all the data from all the involved backends in an endpoint, the merge operation takes place. Once KrakenD merges all the data from the backends in a final object, it uses it as input of the JMESPath query expression. The output of this component is then returned to the user.

JMESPath configuration

The configuration to set in KrakenD is straightforward as it only needs to receive the expression to execute in the endpoint or the backend.

{
    "endpoint": "/advanced-manipulation",
    "extra_config": {
        "modifier/jmespath": {
            "expr": "students[?age > `18` ].name"
        }
    }
}

Output wrappers

As it happens with the rest of the content in KrakenD, depending on the type of content that the JMESPath expression returns, KrakenD will wrap it or not inside a key:

• collection: When the backend returns an array, KrakenD adds the collection. You can remove this collection key in the final response by setting the output_encoding in the endpoint to json-collection (see content types)
• content: when the JMESPath expression returns just a string, a boolean, or a number, then KrakenD adds a content wrapper. You can remove it automatically when setting the output_encoding to string.

Reusing the same example above, the following configurations have these effects:

{
    "endpoint": "/advanced-manipulation",
    "extra_config": {
        "modifier/jmespath": {
            "expr": "students[?age > `18` ].name"
        }
    }
}

Returns:

{
    "collection": ["Bill", "Jessica"]
}

While if we add the output_encoding expecting a JSON collection:

{
    "endpoint": "/advanced-manipulation",
    "output_encoding": "json-collection",
    "extra_config": {
        "modifier/jmespath": {
            "expr": "students[?age > `18` ].name"
        }
    }
}

Then we get the collection directly in the output:

["Bill", "Jessica"]

The same happens with the "output_encoding": "string" when the query returns a single value.