Routes

Routes define how inbound requests are mapped to downstream (outbound) services.

Basic Route

A route maps an inbound path to an outbound service:

{
  "UpstreamPathTemplate": "/api/users",
  "UpstreamHttpMethod": ["GET", "POST"],
  "DownstreamPathTemplate": "/api/v1/users",
  "DownstreamScheme": "http",
  "DownstreamHostAndPorts": [
    { "Host": "localhost", "Port": 3000 }
  ]
}

Path Placeholders

Use {placeholders} to capture path segments:

{
  "UpstreamPathTemplate": "/api/users/{userId}",
  "DownstreamPathTemplate": "/api/v1/users/{userId}"
}

Complex Placeholders

Inbound:  /api/invoices_{company}/{id}-{version}_data/{ref}
Outbound: /api/invoices_{company}/{id}-{version}_data/{ref}

Catch-All Routes

Match all incoming traffic with a wildcard:

{
  "UpstreamPathTemplate": "/{catchAll}",
  "DownstreamPathTemplate": "/{catchAll}"
}

note

Catch-all routes have the lowest priority (0). Other routes will match first.

Priority

Control route matching order with the Priority field. Higher values match first:

{
  "UpstreamPathTemplate": "/api/users/{id}",
  "Priority": 1
}

Query String Routing

Path to Query String

{
  "UpstreamPathTemplate": "/api/units/{subscription}/{unit}/updates",
  "DownstreamPathTemplate": "/api/subscriptions/{subscription}/updates?unitId={unit}"
}

Catch-All Query String

Forward all query parameters:

{
  "UpstreamPathTemplate": "/contracts?{query}",
  "DownstreamPathTemplate": "/api/path/contracts?{query}"
}

Route Key

Each route can have a unique Key for identification:

{
  "Key": "users-service",
  "UpstreamPathTemplate": "/api/users",
  "DownstreamPathTemplate": "/api/users"
}

The key is used in aggregation and for reference in the admin panel.

Rate Limiting

Protect routes from excessive requests:

{
  "RateLimitOptions": {
    "EnableRateLimiting": true,
    "Period": "1m",
    "Limit": 100,
    "PeriodTimespan": 5,
    "ClientWhitelist": ["admin-client"]
  }
}

Field	Description
Period	Time window: 1s, 1m, 1h, 1d
Limit	Max requests per period
PeriodTimespan	Cooldown in seconds after limit is exceeded
ClientWhitelist	Clients exempt from rate limiting

Caching

Cache downstream responses:

{
  "CacheOptions": {
    "TtlSeconds": 30,
    "Region": "users",
    "Header": "OC-Cache-Control",
    "EnableContentHashing": false
  }
}

Load Balancing

Distribute requests across multiple downstream hosts:

{
  "DownstreamHostAndPorts": [
    { "Host": "server1", "Port": 3000 },
    { "Host": "server2", "Port": 3000 }
  ],
  "LoadBalancerOptions": {
    "Type": "RoundRobin"
  }
}

Available types: RoundRobin, LeastConnection, CookieStickySessions, NoLoadBalancer.

QoS (Quality of Service)

Circuit breaker pattern powered by Polly:

{
  "QoSOptions": {
    "ExceptionsAllowedBeforeBreaking": 3,
    "DurationOfBreak": 5000,
    "TimeoutValue": 3000
  }
}

Security Options

IP-based access control with CIDR support:

{
  "SecurityOptions": {
    "IPAllowedList": ["192.168.1.0/24"],
    "IPBlockedList": ["10.0.0.0/8"],
    "ExcludeAllowedFromBlocked": true
  }
}

Supported formats: single IP, IP range, short range, subnet mask, CIDR (v4/v6).

Header Transformation

Add Headers to Outbound Request

{
  "UpstreamHeaderTransform": {
    "X-Custom-Header": "value"
  }
}

Transform Response Headers

{
  "DownstreamHeaderTransform": {
    "Location": "http://internal:5000, {BaseUrl}"
  }
}

Available placeholders: {BaseUrl}, {DownstreamBaseUrl}, {RemoteIpAddress}, {TraceId}, {UpstreamHost}.

Claims Transformation

Transform JWT claims into headers, query strings, or path parameters:

{
  "AddHeadersToRequest": {
    "CustomerId": "Claims[sub] > value[1] > |"
  },
  "AddQueriesToRequest": {
    "LocationId": "Claims[LocationId] > value"
  },
  "ChangeDownstreamPathTemplate": {
    "userId": "Claims[sub] > value[1] > |"
  }
}

Tracing

Enable per-route request tracing:

{
  "DelegatingHandlers": ["Tracing"],
  "Metadata": {
    "TraceEndpointUrl": "http://your-tracing-service:3000/trace"
  }
}

When enabled, the gateway sends request details (URL, method, headers, body) to the configured trace endpoint.

warning

Sensitive headers (Authorization, Cookie, X-Api-Key) are automatically stripped from trace payloads.