Skip to main content

​
Endpoint Configuration

Endpoints are the URLs that KrakenD exposes to clients. Each endpoint can aggregate data from one or more backends, apply transformations, and add middleware functionality.

​
Endpoint Structure

Basic endpoint structure: 
{
  "endpoint": "/git/{user}",
  "method": "GET",
  "cache_ttl": "1s",
  "backend": [...],
  "extra_config": {...}
}

​
Endpoint Properties

PropertyTypeRequiredDescription
endpointstringYesURL pattern exposed by the gateway
methodstringNoHTTP method (defaults to GET)
backendarrayYesList of backend services to call
cache_ttlstringNoOverride global cache TTL for this endpoint
concurrent_callsnumberNoNumber of concurrent calls to the same backend
extra_configobjectNoAdditional middleware configuration

​
Backend Configuration

Backends define the upstream services that KrakenD calls to fetch data: 
{
  "host": ["https://api.github.com"],
  "url_pattern": "/users/{user}",
  "method": "GET",
  "encoding": "json",
  "allow": ["avatar_url", "name", "company"],
  "mapping": {"blog": "website"},
  "group": "user",
  "is_collection": false,
  "target": "",
  "extra_config": {...}
}

​
Backend Properties

PropertyTypeDescription
hostarrayBackend host URLs
url_patternstringURL path with optional parameters
allowarrayWhitelist of fields to include in response
mappingobjectRename fields in the response
groupstringWrap response in a named object
is_collectionbooleanIndicates if response is an array
targetstringExtract data from a specific field
encodingstringResponse encoding (json, safejson, xml, etc.)
extra_configobjectBackend-specific middleware

​
Real-World Examples

​
Example 1: Data Aggregation and Transformation

This endpoint aggregates GitHub user data and repositories: 
{
  "endpoint": "/git/{user}",
  "backend": [
    {
      "host": ["https://api.github.com"],
      "url_pattern": "/users/{user}",
      "allow": [
        "avatar_url",
        "name",
        "company",
        "blog",
        "location",
        "followers",
        "public_repos"
      ],
      "mapping": {
        "blog": "website"
      },
      "group": "user"
    },
    {
      "host": ["https://api.github.com"],
      "url_pattern": "/users/{user}/repos",
      "mapping": {
        "collection": "repos"
      },
      "is_collection": true
    }
  ]
}
Features demonstrated:
  • Aggregation: Calls two different GitHub API endpoints
  • Filtering: Uses allow to whitelist specific fields
  • Mapping: Renames blog to website
  • Grouping: Wraps user data in a user object
  • Collections: Properly handles array responses

​
Example 2: GraphQL to REST

This endpoint transforms a GraphQL query into a REST API: 
{
  "endpoint": "/starwars_films/{movie_id}",
  "backend": [
    {
      "host": ["https://swapi-graphql.netlify.app/"],
      "url_pattern": "/.netlify/functions/index",
      "target": "data.film",
      "extra_config": {
        "backend/graphql": {
          "type": "query",
          "query": "query Query ($movie_id: ID!) {\nfilm (filmID: $movie_id) {\nid\nepisodeID\ntitle\ndirector\nreleaseDate\n}\n}",
          "variables": {
            "movie_id": "{movie_id}"
          }
        }
      }
    }
  ]
}
Features demonstrated:
  • GraphQL integration: Converts GraphQL to REST
  • Target extraction: Uses target to extract nested data
  • Variable injection: Passes URL parameters to GraphQL query

​
Example 3: Sequential Calls

This endpoint makes sequential calls, using data from the first response in the second request: 
{
  "endpoint": "/sequential",
  "backend": [
    {
      "url_pattern": "/hotels/1.json",
      "allow": ["destination_id"]
    },
    {
      "url_pattern": "/destinations/{resp0_destination_id}.json"
    }
  ],
  "extra_config": {
    "proxy": {
      "sequential": true
    }
  }
}
Features demonstrated:
  • Sequential proxy: Enables sequential calls with "sequential": true
  • Response injection: Uses {resp0_destination_id} from first response

​
Extra Config Options

​
Rate Limiting

Endpoint-level rate limiting: 
"extra_config": {
  "qos/ratelimit/router": {
    "max_rate": 2
  }
}
Backend-level rate limiting: 
"extra_config": {
  "qos/ratelimit/proxy": {
    "max_rate": 1,
    "capacity": 1
  }
}

​
JWT Validation

Protect endpoints with JWT token validation: 
"extra_config": {
  "auth/validator": {
    "alg": "RS256",
    "audience": ["playground"],
    "roles_key": "realm_access.roles",
    "roles": ["moderator"],
    "jwk_url": "http://keycloak:8080/realms/krakend/protocol/openid-connect/certs"
  }
}

​
Response Manipulation

Use flatmap filter to transform response data: 
"extra_config": {
  "proxy": {
    "flatmap_filter": [
      {
        "type": "move",
        "args": ["collection", "coins"]
      },
      {
        "type": "del",
        "args": ["coins.*.unwanted_field"]
      }
    ]
  }
}

​
Backend Caching

Cache backend responses based on HTTP headers: 
"extra_config": {
  "qos/http-cache": {
    "shared": true
  }
}

​
Mocked Responses

Return static data without calling backends: 
"extra_config": {
  "proxy": {
    "static": {
      "data": {
        "an_integer": 123,
        "an_array": ["arr1", "arr2"],
        "an_object": {"obj": "obj1"}
      },
      "strategy": "always"
    }
  }
}

​
Method Restrictions

By default, endpoints accept GET requests. To restrict methods: 
{
  "endpoint": "/post",
  "method": "POST",
  "backend": [{
    "url_pattern": "/__debug/post"
  }]
}

​
Concurrent Requests

Make multiple concurrent calls to the same backend: 
{
  "endpoint": "/market/concurrent",
  "concurrent_calls": 3,
  "backend": [{
    "host": ["https://api.coingecko.com"],
    "url_pattern": "/api/v3/coins/markets?vs_currency=eur"
  }]
}

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us