Traffic Splitting

Safely roll out new versions of your upstream services or run A/B tests by routing a percentage of traffic to different variants.

Quickstart

Add trafficConfig to split traffic 80/20 between your stable API and a new v2 release.

{
  "trafficEnabled": true,
  "trafficConfig": {
    "testName": "api-v2-rollout",
    "variants": [
      {
        "id": "stable",
        "targetUrl": "https://api.example.com/v1",
        "weight": 80
      },
      {
        "id": "beta",
        "targetUrl": "https://api.example.com/v2",
        "weight": 20
      }
    ]
  }
}

Reference

Field	Type	Default	Required	Description
trafficEnabled	boolean	false	No	Boolean to enable/disable traffic splitting for the route.
testName	string	-	No	Easily identifiable name for the traffic split test.
variants	array of objects	-	Yes	Array of target URLs and their traffic weights. Requires 2 to 10 variants.
sticky	boolean	false	No	Ensure a specific client always hits the same variant.
stickyKey	string	-	No	The header or property used to identify unique clients (e.g., `Authorization`).

Variant Object

Field	Type	Required	Description
id	string	Yes	Unique identifier for the variant.
targetUrl	string (URI)	Yes	The URL to forward the traffic to.
weight	integer	Yes	Percentage of traffic (0-100) to send to this variant. All variant weights must sum to 100.
headers	object	No	Custom headers to inject when this variant is chosen.

Examples

Sticky Session A/B Test

Send 50% of users to a new checkout flow, ensuring each user stays on their assigned variant based on their x-user-id header.

{
  "trafficEnabled": true,
  "trafficConfig": {
    "testName": "checkout-flow-ab",
    "sticky": true,
    "stickyKey": "x-user-id",
    "variants": [
      {
        "id": "control",
        "targetUrl": "https://api.example.com/checkout/v1",
        "weight": 50
      },
      {
        "id": "experiment",
        "targetUrl": "https://api.example.com/checkout/v2",
        "weight": 50,
        "headers": {
          "x-experiment-group": "v2"
        }
      }
    ]
  }
}

Common Errors

400 Bad Request

Invalid configuration format

Returned errors: variants: must NOT have fewer than 2 items or weight: must be <= 100.

Fix: Provide at least two variants and ensure individual weights do not exceed 100.