response-flatmap.md

title	Response Flatmap & Target
sidebar_position	4

Flatmap and target extend the body transform engine with response data shaping capabilities inspired by KrakenD's response manipulation.

Target

The target field extracts a nested JSON path as the root response, discarding the wrapper object.

routes:
  - id: api-users
    path: /api/users
    backends:
      - url: http://backend:8080
    transform:
      response:
        body:
          target: data.users

Given a backend response:

{"status": "ok", "data": {"users": [{"id": 1}, {"id": 2}]}}

The gateway returns:

[{"id": 1}, {"id": 2}]

If the target path does not exist, the original response is returned unchanged.

Flatmap Operations

Flatmap operations manipulate arrays and values in the response body. They run after all other field operations (set/add/remove/rename) and before the template.

routes:
  - id: api-products
    path: /api/products
    backends:
      - url: http://backend:8080
    transform:
      response:
        body:
          flatmap:
            - type: extract
              args: [items, name]
            - type: move
              args: [items, product_names]
            - type: del
              args: [debug]

Supported Operations

Type	Args	Description
move	[source, dest]	Move a value from source path to dest path
del	[path]	Delete a path
extract	[array_path, field]	Extract a field from each object in an array
flatten	[path]	Flatten nested arrays into a single array
append	[dest, src1, src2, ...]	Concatenate source arrays into dest

Extract Example

// Input
{"users": [{"id": 1, "name": "alice"}, {"id": 2, "name": "bob"}]}

// flatmap: [{type: extract, args: [users, name]}]
{"users": ["alice", "bob"]}

Flatten Example

// Input
{"matrix": [[1, 2], [3, 4], [5]]}

// flatmap: [{type: flatten, args: [matrix]}]
{"matrix": [1, 2, 3, 4, 5]}

Append Example

// Input
{"page1": ["a", "b"], "page2": ["c", "d"]}

// flatmap: [{type: append, args: [all, page1, page2]}]
{"page1": ["a", "b"], "page2": ["c", "d"], "all": ["a", "b", "c", "d"]}

Processing Order

The full body transform processing order is:

1. target — extract nested path as root
2. allow_fields / deny_fields — field filtering
3. set_fields — set values at paths
4. add_fields — add top-level fields
5. remove_fields — remove paths
6. rename_fields — rename paths
7. flatmap — array manipulation
8. template — Go template (terminal, replaces the entire response body)

The template step (8) is terminal — it replaces the entire response body with the template output. Prior steps (target, field filtering, flatmap) still run first, so the flatmap output becomes the template input. This means you can use flatmap to reshape data and then template to produce the final output format.

Combined Example

transform:
  response:
    body:
      target: data
      deny_fields: [internal_id, debug]
      flatmap:
        - type: extract
          args: [items, name]
        - type: flatten
          args: [tags]

Admin API

Flatmap and target are part of the existing body transform pipeline. No separate admin endpoint is needed — stats are included in the route's transform metrics.