Skip to main content

​
Overview

Data aggregation is one of KrakenD’s most powerful features. It allows you to merge responses from multiple backend services into a single unified response, reducing the number of client requests and network overhead.

​
Example: GitHub User Profile

The /git/{user} endpoint demonstrates aggregation by combining:
  1. GitHub user profile data
  2. User’s repository list
Into a single response with filtered and transformed fields.

​
Try It

curl http://localhost:8080/git/krakend

​
Configuration

Here’s the complete endpoint configuration from config/krakend/krakend.json: 
{
  "endpoint": "/git/{user}",
  "backend": [
    {
      "host": ["https://api.github.com"],
      "url_pattern": "/users/{user}",
      "allow": [
        "avatar_url",
        "name",
        "company",
        "blog",
        "location",
        "mail",
        "hireable",
        "followers",
        "public_repos",
        "public_gists"
      ],
      "mapping": {
        "blog": "website"
      },
      "group": "user"
    },
    {
      "host": ["https://api.github.com"],
      "url_pattern": "/users/{user}/repos",
      "mapping": {
        "collection": "repos"
      },
      "is_collection": true
    }
  ]
}

​
Key Features

​
1. Field Filtering with allow

The allow list acts as a whitelist, only passing through specified fields: 
"allow": [
  "avatar_url",
  "name",
  "company",
  "blog",
  "location"
]
This reduces response size and prevents exposing unnecessary data.

​
2. Field Mapping

Rename fields in the response using mapping: 
"mapping": {
  "blog": "website"
}
The GitHub API’s blog field becomes website in the final response.

​
3. Response Grouping

The group parameter nests the backend response under a specific key: 
"group": "user"
The user profile data appears under user in the aggregated response: 
{
  "user": {
    "name": "KrakenD",
    "website": "https://krakend.io",
    "followers": 150
  },
  "repos": [...]
}

​
4. Collection Handling

Mark array responses with is_collection: 
"is_collection": true,
"mapping": {
  "collection": "repos"
}
This properly handles the repository list and maps it to the repos key.

​
Response Structure

Without KrakenD, the client would need 2 separate requests:
  1. GET https://api.github.com/users/krakend
  2. GET https://api.github.com/users/krakend/repos
With KrakenD aggregation, one request to /git/krakend returns: 
{
  "user": {
    "avatar_url": "https://avatars.githubusercontent.com/u/...",
    "name": "KrakenD",
    "company": "@krakend",
    "website": "https://krakend.io",
    "location": "Barcelona",
    "hireable": null,
    "followers": 150,
    "public_repos": 42,
    "public_gists": 0
  },
  "repos": [
    {
      "name": "krakend-ce",
      "full_name": "krakend/krakend-ce",
      "description": "High performance API Gateway"
    }
  ]
}

​
Benefits

  • Reduced Client Complexity - One request instead of multiple
  • Lower Latency - Parallel backend calls
  • Data Privacy - Filter sensitive fields
  • Response Shaping - Transform data to match client needs
  • Network Efficiency - Smaller payload sizes

​
Advanced Aggregation

For more complex transformations, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us