Advanced Route Configuration

Take full control of your API routing with advanced configuration options. Inject headers, transform request bodies, configure method-specific behaviors, and dynamically inject secrets.

Header Injection

Automatically add or modify headers on all requests:

Static Headers

Add fixed headers to every request:

{
  "X-API-Version": "v2",
  "X-Service-Name": "knoxcall-proxy",
  "X-Environment": "production"
}

Configuration:

Edit route → Header Injection section
Add headers in JSON format
Save

Example request:

# Client sends:
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-route: my-route"

# KnoxCall forwards with injected headers:
GET /api/users
X-API-Version: v2
X-Service-Name: knoxcall-proxy
X-Environment: production

Secret Injection

Inject encrypted secrets as headers:

{
  "Authorization": "Bearer {{secret:api_token}}",
  "X-API-Key": "{{secret:stripe_key}}",
  "X-Custom-Auth": "{{secret:custom_credential}}"
}

KnoxCall automatically:

Retrieves secret from encrypted vault
Decrypts at request time
Injects into header
Never logs the actual value

Dynamic Headers

Use variables in header values:

{
  "X-Client-ID": "{{client.id}}",
  "X-Client-Name": "{{client.name}}",
  "X-Route-Name": "{{route.name}}",
  "X-Environment": "{{environment}}",
  "X-Timestamp": "{{timestamp}}",
  "X-Request-ID": "{{request_id}}"
}

Available variables:

{{client.id}} - Client UUID
{{client.name}} - Client name
{{route.name}} - Route name
{{environment}} - Current environment
{{timestamp}} - Unix timestamp
{{request_id}} - Unique request ID
{{tenant_id}} - Tenant UUID

Conditional Headers

Add headers based on conditions:

{
  "X-API-Key": "{{if environment == 'production'}}{{secret:prod_key}}{{else}}{{secret:test_key}}{{endif}}",
  "X-Debug": "{{if environment == 'development'}}true{{endif}}"
}

Body Injection

Inject fields into JSON request bodies:

Static Fields

Add fixed fields:

{
  "source": "knoxcall",
  "version": "1.0",
  "metadata": {
    "proxied": true
  }
}

Original request body:

{
  "username": "john",
  "email": "[email protected]"
}

Forwarded body:

{
  "username": "john",
  "email": "[email protected]",
  "source": "knoxcall",
  "version": "1.0",
  "metadata": {
    "proxied": true
  }
}

Secret Injection in Body

Inject secrets into request bodies:

{
  "api_key": "{{secret:printnode_key}}",
  "client_secret": "{{secret:oauth_client_secret}}",
  "credentials": {
    "username": "{{secret:service_username}}",
    "password": "{{secret:service_password}}"
  }
}

Body injection only works with JSON payloads. Non-JSON bodies are passed through unchanged.

Nested Field Injection

Inject into nested structures:

{
  "auth": {
    "type": "bearer",
    "token": "{{secret:bearer_token}}"
  },
  "options": {
    "timeout": 30,
    "retry": true
  }
}

Method-Specific Configuration

Configure different behaviors per HTTP method:

Setup

Edit route → Method Configurations tab
Add configuration for each method
Configure headers, body, secrets per method

Example: Read/Write Separation

GET:
  Headers:
    Authorization: "Bearer {{secret:read_only_key}}"
  Rate Limit: 5000/hour

POST:
  Headers:
    Authorization: "Bearer {{secret:write_key}}"
  Body Injection:
    created_by: "knoxcall"
  Rate Limit: 1000/hour

PUT:
  Headers:
    Authorization: "Bearer {{secret:write_key}}"
  Body Injection:
    updated_by: "knoxcall"
  Rate Limit: 1000/hour

DELETE:
  Headers:
    Authorization: "Bearer {{secret:admin_key}}"
  Require Signature: true
  Rate Limit: 100/hour

Benefits

Security: Use different credentials per action
Rate Limiting: Restrict writes more than reads
Auditing: Track who performs each action type
Compliance: Enforce stricter rules on destructive operations

Query Parameter Injection

Add or modify query parameters:

Static Parameters

Query Parameters:
  api_version: "2"
  source: "knoxcall"

Client request:

GET /api/users?status=active

Forwarded:

GET /api/users?status=active&api_version=2&source=knoxcall

Dynamic Parameters

Query Parameters:
  client_id: "{{client.id}}"
  timestamp: "{{timestamp}}"

Path Transformation

Modify request paths:

Path Prefix

Add prefix to all paths:

Path Prefix: /api/v2

Client request:

GET /users

Forwarded:

GET /api/v2/users

Path Rewriting

Rewrite paths with patterns:

Path Rewrite:
  - Pattern: ^/v1/(.*)
    Replace: /api/v2/$1

  - Pattern: ^/legacy/(.*)
    Replace: /modern/$1

Examples:

/v1/users → /api/v2/users
/v1/orders/123 → /api/v2/orders/123
/legacy/products → /modern/products

Timeout Configuration

Set custom timeouts:

Timeouts:
  Connection: 5s    # Time to establish connection
  Read: 30s        # Time to read response
  Write: 10s       # Time to send request
  Total: 60s       # Maximum total time

Per-Endpoint Timeouts

Endpoint Timeouts:
  /api/reports/generate:
    Total: 300s    # 5 minutes for report generation

  /api/batch/process:
    Total: 600s    # 10 minutes for batch jobs

  Default:
    Total: 30s     # 30 seconds for everything else

Retry Configuration

Automatic retries on failure:

Retry Policy:
  Max Attempts: 3
  Initial Delay: 1s
  Max Delay: 30s
  Backoff Multiplier: 2
  Retry On:
    - 502 Bad Gateway
    - 503 Service Unavailable
    - 504 Gateway Timeout
    - Connection timeout
  Do Not Retry On:
    - 4xx errors (client errors)
    - 500 Internal Server Error

Example:

Attempt 1: Fails with 502 → Wait 1s
Attempt 2: Fails with 502 → Wait 2s
Attempt 3: Succeeds ✅

Circuit Breaker

Protect backends from cascading failures:

Circuit Breaker:
  Enabled: true
  Failure Threshold: 5      # Open after 5 failures
  Success Threshold: 2      # Close after 2 successes
  Timeout: 60s             # Try again after 60s
  Half-Open Requests: 1    # Test with 1 request when half-open

States:

Closed (Normal)
    ↓ (5 failures)
Open (Blocking requests)
    ↓ (60 seconds)
Half-Open (Testing)
    ↓ (2 successes)
Closed (Recovered)

Load Balancing

Distribute requests across multiple backends:

Load Balancing:
  Algorithm: round_robin   # or: least_connections, ip_hash
  Backends:
    - url: https://backend1.example.com
      weight: 3
    - url: https://backend2.example.com
      weight: 2
    - url: https://backend3.example.com
      weight: 1
  Health Checks:
    Interval: 30s
    Timeout: 5s
    Path: /health

Algorithms:

Round Robin: Rotate through backends evenly
Least Connections: Send to backend with fewest active connections
IP Hash: Same client always goes to same backend

Request/Response Transformation

Request Body Transformation

Transform JSON before forwarding:

// JavaScript transformation function
function transformRequest(body) {
  return {
    ...body,
    timestamp: Date.now(),
    user_id: body.userId,  // Rename field
    metadata: {
      original_ip: request.clientIP,
      route: request.route
    }
  };
}

Response Body Transformation

Transform JSON before returning to client:

function transformResponse(body) {
  // Remove sensitive fields
  delete body.internal_id;
  delete body.server_info;

  // Add wrapper
  return {
    success: true,
    data: body,
    timestamp: Date.now()
  };
}

Custom Error Responses

Override backend error responses:

Error Responses:
  404:
    status: 404
    body:
      error: "Resource not found"
      message: "The requested resource does not exist"
      support: "https://support.knoxcall.com"

  503:
    status: 503
    body:
      error: "Service temporarily unavailable"
      message: "Our service is undergoing maintenance"
      retry_after: 300

  500:
    status: 500
    body:
      error: "Internal error"
      message: "An unexpected error occurred"
      request_id: "{{request_id}}"

WebSocket Support

Enable WebSocket proxying:

WebSocket:
  Enabled: true
  Timeout: 3600s          # 1 hour
  Max Message Size: 1MB
  Compression: true

Upgrade automatically:

Client: ws://a1b2c3d4.acme.knoxcall.com/socket
    ↓
KnoxCall upgrades connection
    ↓
Backend: ws://backend.example.com/socket

gRPC Support

Proxy gRPC requests:

gRPC:
  Enabled: true
  HTTP2: true
  TLS: true
  Max Message Size: 4MB

Caching

Cache responses to reduce backend load:

Caching:
  Enabled: true
  TTL: 300s               # 5 minutes
  Cache Key: "{{method}}.{{path}}.{{query}}"
  Cache On:
    - GET
    - HEAD
  Skip Cache If:
    - Cache-Control: no-cache header present
    - Authorization header present

Cache headers returned:

X-Cache: HIT
X-Cache-Age: 45
Cache-Control: max-age=300

Compression

Enable response compression:

Compression:
  Enabled: true
  Algorithms:
    - gzip
    - br (Brotli)
  Minimum Size: 1KB
  Content Types:
    - application/json
    - text/html
    - text/plain

Custom Middleware

Add custom processing logic:

// Pre-request middleware
async function beforeRequest(request) {
  // Validate request
  if (!request.headers['x-custom-header']) {
    throw new Error('Missing required header');
  }

  // Modify request
  request.headers['x-processed'] = 'true';

  return request;
}

// Post-response middleware
async function afterResponse(response) {
  // Log response
  console.log(`Response: ${response.status}`);

  // Modify response
  response.headers['x-powered-by'] = 'KnoxCall';

  return response;
}

Best Practices

1. Use Secrets for Sensitive Data

❌ Bad:

{
  "Authorization": "Bearer sk_live_abc123xyz789"
}

✅ Good:

{
  "Authorization": "Bearer {{secret:api_token}}"
}

2. Validate Injected Data

Ensure injected values are valid:

function validateInjection(value) {
  if (!value || value === '{{secret:missing_key}}') {
    throw new Error('Secret not found');
  }
  return value;
}

3. Use Method-Specific Configs

Different security for different operations:

GET: read_only_key
POST/PUT/DELETE: write_key with signature required

4. Enable Circuit Breakers for Critical Routes

Protect payment and order routes:

payment-api:
  Circuit Breaker: Enabled
  Retry: Disabled  # Don't retry payments!

5. Monitor Transformation Performance

Check transformation time in logs:

Transformation time: 5ms
Total latency: 85ms (transformation: 6%)

Next Steps

Method-Specific Config

Deep dive into method configs

Secret Management

Learn about secrets

Rate Limiting

Configure rate limits

Request Signing

Add signature verification

📊 Statistics

Level: advanced
Time: 25 minutes

🏷️ Tags

advanced, configuration, headers, transformation, routing

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​Advanced Route Configuration

​Header Injection

​Static Headers

​Secret Injection

​Dynamic Headers

​Conditional Headers

​Body Injection

​Static Fields

​Secret Injection in Body

​Nested Field Injection

​Method-Specific Configuration

​Setup

​Example: Read/Write Separation

​Benefits

​Query Parameter Injection

​Static Parameters

​Dynamic Parameters

​Path Transformation

​Path Prefix

​Path Rewriting

​Timeout Configuration

​Per-Endpoint Timeouts

​Retry Configuration

​Circuit Breaker

​Load Balancing

​Request/Response Transformation

​Request Body Transformation

​Response Body Transformation

​Custom Error Responses

​WebSocket Support

​gRPC Support

​Caching

​Compression

​Custom Middleware

​Best Practices

​1. Use Secrets for Sensitive Data

​2. Validate Injected Data

​3. Use Method-Specific Configs

​4. Enable Circuit Breakers for Critical Routes

​5. Monitor Transformation Performance

​Next Steps

Method-Specific Config

Secret Management

Rate Limiting

Request Signing

📊 Statistics

🏷️ Tags

Advanced Route Configuration

Header Injection

Static Headers

Secret Injection

Dynamic Headers

Conditional Headers

Body Injection

Static Fields

Secret Injection in Body

Nested Field Injection

Method-Specific Configuration

Setup

Example: Read/Write Separation

Benefits

Query Parameter Injection

Static Parameters

Dynamic Parameters

Path Transformation

Path Prefix

Path Rewriting

Timeout Configuration

Per-Endpoint Timeouts

Retry Configuration

Circuit Breaker

Load Balancing

Request/Response Transformation

Request Body Transformation

Response Body Transformation

Custom Error Responses

WebSocket Support

gRPC Support

Caching

Compression

Custom Middleware

Best Practices

1. Use Secrets for Sensitive Data

2. Validate Injected Data

3. Use Method-Specific Configs

4. Enable Circuit Breakers for Critical Routes

5. Monitor Transformation Performance

Next Steps