Proxy Multiple Backends Behind One Domain

The short answer: One gateway domain works best when each route block has a clear upstream owner, a predictable path contract, and only the minimum request transformation you truly need.

When to read this

• You have multiple services but want one client-facing API hostname.
• You want path-level routing and prefix rewrites without another reverse proxy product.
• You want to centralize cross-cutting concerns before requests hit downstream services.

What matters in practice

• Model each upstream once under servers and reference it by alias.
• Use wildcard routes carefully so a broad proxy does not outrank specific endpoints.
• Keep request mapping close to the route that needs it.

Concrete example

        {
        "servers": [
          { "alias": "users", "url": "https://users.example.com" },
          { "alias": "orders", "url": "https://orders.example.com" }
        ],
        "paths": [
          { "method": "GET", "path": "/api/users/{.+}", "integration": { "type": "http_proxy", "server": "users" } },
          { "method": "GET", "path": "/api/orders/{.+}", "integration": { "type": "http_proxy", "server": "orders" } }
        ]
      }

The example above is intentionally small because the best gateway configs stay readable. Add only the route, auth, and mapping behavior you actually need.

How this maps to the current gateway

The current codebase already supports the behavior discussed here through its config schema, route matcher, and integration handlers. That is why this project is a good fit for reader-first examples: the docs and blog can point to real, implemented behavior instead of hypothetical gateway features.

What this product does not do

• The gateway does not implement traffic splitting or canary release logic.
• Per-upstream observability and analytics are not included out of the box.

FAQ

Can one upstream handle a wildcard subtree?

Yes. The current route matching and proxy rewriting support wildcard segments.

Should each service still own business auth?

Yes. The gateway can verify identity and shape requests, but downstream authorization rules still matter.

Related docs

• routing multi upstream patterns
• routing prefix add remove
• choosing proxy vs service

Last reviewed: March 6, 2026