Why Wildcard Routes Go Wrong

The short answer: Wildcard routes go wrong when they are introduced before the team defines the exact routes that need stronger guarantees.

When to read this

• You proxy a subtree to an upstream service.
• You mix exact paths, path params, and catch-all routes.
• You are debugging unexpected route matches.

What matters in practice

• Exact matches beat parameterized ones, which beat wildcard routes.
• A clean route tree is easier to maintain than a clever one.
• Document the catch-all use case explicitly so it stays narrow.

Concrete example

        {
        "paths": [
          { "method": "GET", "path": "/orders/{id}", "integration": { "type": "http_proxy", "server": "orders" } },
          { "method": "GET", "path": "/orders/{.+}", "integration": { "type": "http_proxy", "server": "legacy-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

• Wildcard routing does not replace deliberate API design.
• A bad route tree can still be confusing even with deterministic match rules.

FAQ

Does method matter in route priority?

Yes. The gateway prefers a concrete HTTP method over ANY when both match.

Should I use wildcard for everything under /api?

Usually no. Start specific, then add a catch-all only where it saves real duplication.

Related docs

• routing exact vs parameter vs wildcard
• routing path priority explained
• routing any method

Last reviewed: March 6, 2026