Routes

A Route defines how to match incoming HTTP requests and what to do with them. It’s the core of Vrata’s traffic management — every request that hits the proxy is evaluated against the route table to find a match.

What a route does

  1. Matches requests — by path, headers, methods, hostnames, query params, gRPC flag, or CEL expressions
  2. Decides what action to take — forward to a backend, redirect, or return a fixed response
  3. Applies middlewares — any number of middlewares in order

Each route operates in exactly one of three modes: forward, redirect, or directResponse.

Creating a route

curl -X POST localhost:8080/api/v1/routes \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "api-route",
    "match": {"pathPrefix": "/api/v1"},
    "forward": {
      "destinations": [{"destinationId": "<dest-id>", "weight": 100}]
    }
  }'

Structure

{
  "name": "api-route",
  "match": { ... },
  "forward": {
    "destinations": [{"destinationId": "<id>", "weight": 100}],
    "destinationBalancing": { ... },
    "timeouts": { ... },
    "retry": { ... },
    "rewrite": { ... },
    "mirror": { ... },
    "maxGrpcTimeout": "0s"
  },
  "redirect": { ... },
  "directResponse": { ... },
  "middlewareIds": ["jwt-auth", "cors"],
  "middlewareOverrides": { ... }
}

Only one of forward, redirect, or directResponse should be set.

All fields

FieldTypeDescriptionDetails
namestringUnique name—
matchobjectRequest matching rulesMatching
forwardobjectForward to upstream destinationsForwarding
redirectobjectReturn HTTP redirect (url, scheme, host, path, stripQuery, code)Redirect
directResponseobjectReturn fixed response (status, body)Direct Response
middlewareIdsarrayMiddleware IDs to apply (in order)—
middlewareOverridesmapPer-middleware overrides (skipWhen, onlyWhen, disabled)—

Route priority

Routes are evaluated in this order:

  1. Exact path matches first (path)
  2. Then prefix matches, longest prefix first (pathPrefix)
  3. Then regex matches (pathRegex)
  4. Within the same path type, more specific matchers (more headers, hostnames, etc.) win

The first matching route handles the request. If no route matches, Vrata returns a structured JSON error. The detail level is controlled by the listener’s proxyErrors setting.