KrakenD API Gateway setup for web application

API Gateway Setup (KrakenD) for Web Application

KrakenD is a stateless API Gateway written in Go with declarative configuration in a single JSON/YAML file. Key feature: aggregating responses from multiple backend services into a single response (API composition). One of the fastest API Gateways — up to 70K+ RPS per core.

Key Concepts

Endpoint — the URL visible to the client. One endpoint can call multiple backend services and combine their responses.

Backend — an internal service. One endpoint can have multiple backends.

Aggregation — KrakenD makes parallel requests to all backends and returns the combined JSON.

Installation

docker run -p 8080:8080 \
  -v $PWD/krakend.json:/etc/krakend/krakend.json \
  devopsfaith/krakend:2.7 run -c /etc/krakend/krakend.json

Configuration krakend.json

{
  "$schema": "https://www.krakend.io/schema/v3.json",
  "version": 3,
  "name": "MyApp API Gateway",
  "timeout": "3000ms",
  "cache_ttl": "300s",
  "output_encoding": "json",
  "port": 8080,

  "endpoints": [
    {
      "endpoint": "/api/v1/user-profile",
      "method": "GET",
      "output_encoding": "json",
      "backend": [
        {
          "url_pattern": "/users/{JWT_CLAIMS.user_id}",
          "host": ["http://users-service:3000"],
          "mapping": { "data": "user" }
        },
        {
          "url_pattern": "/subscriptions/active?user_id={JWT_CLAIMS.user_id}",
          "host": ["http://billing-service:3001"],
          "mapping": { "plan": "subscription_plan" }
        },
        {
          "url_pattern": "/preferences/{JWT_CLAIMS.user_id}",
          "host": ["http://prefs-service:3002"],
          "mapping": { "settings": "preferences" }
        }
      ],
      "extra_config": {
        "auth/validator": {
          "alg": "RS256",
          "jwk_url": "http://auth-service:4000/.well-known/jwks.json",
          "cache": true,
          "cache_duration": 300
        }
      }
    }
  ]
}

The client makes a single GET /api/v1/user-profile request. KrakenD simultaneously queries all three backend services and returns:

{
  "user": { "id": "123", "name": "Alice" },
  "subscription_plan": "pro",
  "preferences": { "theme": "dark" }
}

Response Field Filtering

{
  "endpoint": "/api/v1/users/{id}",
  "backend": [
    {
      "url_pattern": "/users/{id}",
      "host": ["http://users-service:3000"],
      "allow": ["id", "email", "name", "created_at"],
      "deny": ["password_hash", "internal_notes", "admin_flags"]
    }
  ]
}

Rate Limiting

{
  "endpoint": "/api/v1/search",
  "backend": [{ "url_pattern": "/search", "host": ["http://search:3000"] }],
  "extra_config": {
    "qos/ratelimit/router": {
      "max_rate": 100,
      "client_max_rate": 10,
      "strategy": "ip",
      "capacity": 100,
      "client_capacity": 10
    }
  }
}

JWT Validation

{
  "extra_config": {
    "auth/validator": {
      "alg": "RS256",
      "jwk_url": "https://auth.company.com/.well-known/jwks.json",
      "cache": true,
      "cache_duration": 900,
      "roles": ["admin", "user"],
      "roles_key": "https://company.com/roles",
      "roles_key_is_nested": false,
      "propagate_claims": [
        ["sub", "X-User-ID"],
        ["https://company.com/tenant", "X-Tenant-ID"]
      ]
    }
  }
}

Request Transformation (Martian)

KrakenD uses Google Martian for transformation:

{
  "backend": [
    {
      "url_pattern": "/internal/users",
      "host": ["http://users:3000"],
      "extra_config": {
        "modifier/martian": {
          "header.Modifier": {
            "scope": ["request"],
            "name": "X-Internal-Key",
            "value": "secret-internal-key"
          }
        }
      }
    }
  ]
}

Circuit Breaker

{
  "backend": [
    {
      "url_pattern": "/payments",
      "host": ["http://payments-service:3000"],
      "extra_config": {
        "qos/circuit-breaker": {
          "interval": 60,
          "timeout": 10,
          "max_errors": 5,
          "name": "payments-cb",
          "log_status_change": true
        }
      }
    }
  ]
}

Response Caching

{
  "endpoint": "/api/v1/categories",
  "cache_ttl": "1h",
  "backend": [
    {
      "url_pattern": "/categories",
      "host": ["http://catalog-service:3000"],
      "extra_config": {
        "qos/http-cache": {}
      }
    }
  ]
}

Prometheus Metrics

{
  "extra_config": {
    "telemetry/metrics": {
      "collection_time": "60s",
      "proxy_disabled": false,
      "router_disabled": false,
      "backend_disabled": false,
      "endpoint_disabled": false,
      "listen_address": ":9091"
    },
    "telemetry/opentelemetry": {
      "service_name": "krakend-gateway",
      "exporters": {
        "prometheus": [{ "port": 9090, "disable_metrics": false }],
        "otlp": [{
          "name": "jaeger",
          "host": "jaeger",
          "port": 4317,
          "use_http": false
        }]
      }
    }
  }
}

Configuration Generator

KrakenD Designer — web interface for visual configuration generation: krakend.io/docs/designer/.

Timeline

Basic KrakenD setup with multiple service aggregation, JWT, and rate limiting — 2–3 business days. Complex configuration with transformations and observability — 4–5 days.