Skip to main content

Wildcard Routing and Testing

Use this guide when your proxy path ends with /* and you need one proxy to handle variable suffixes.

When to use wildcard proxies​

Use wildcard paths when the exact child path is not known ahead of time, for example:

  • File/blob download paths (/files/*)
  • Static asset passthrough (/assets/*)
  • Nested partner routes (/partner/*)

Avoid wildcard paths when you can define a bounded, schema-driven path (for example /users/{id}), because explicit parameterized routes are easier to validate and document.

Authoring pattern​

In proxy configuration:

  • Path: use suffix wildcard, e.g. /files/*
  • Target Path: use the matching backend wildcard form expected by the upstream (commonly /storage/* or similar)
  • Methods: restrict to only what the upstream supports

Example:

  • Incoming gateway path: /api/files/reports/2026/q1.csv
  • Collection base path: /api
  • Proxy path: /files/*
  • Target path: /storage/*
  • Forwarded upstream path: /storage/reports/2026/q1.csv

Matching and precedence notes​

Routing still respects collection + method + proxy matching rules:

  1. Match collection base path.
  2. Match method constraints.
  3. Match proxy path against candidate routes.

For overlapping patterns, prefer explicit routes for critical operations and keep wildcard routes as catch-all handlers. Validate behavior with real traffic examples before publishing.

Portal testing flow for wildcard routes​

In Developer Portal testing console:

  1. Open endpoint with wildcard path.
  2. Use the wildcard path input to provide the suffix only.
  3. Add query params if your upstream expects them.
  4. Send and validate response status, body, and latency.

Test matrix (recommended):

  • Shallow suffix: /logo.svg
  • Medium depth suffix: /reports/q1.csv
  • Deep suffix: /region/us-east/customers/42/export.json

Failure signatures​

  • 404: wildcard route did not match as expected, or target path rewrite is incorrect.
  • 405: method is not enabled on proxy or blocked by profile method restrictions.
  • 401/403: profile auth or access constraints failed.
  • 429: policy limits were exceeded.

Validation checklist​

  1. Published wildcard proxy resolves expected suffixes.
  2. Target path rewrite is correct for each suffix depth.
  3. Unauthorized request fails with expected status.
  4. Request appears in logs with expected path, method, and client/profile context.