Modern application architectures are in constant evolution. An endpoint born as API v1 reaches v3; the path structure behind a monolith changes completely after a microservice split; a B2B partner is accustomed to a different URL scheme; or a modernisation project imposes a new path layout. When every change requires reconfiguring either the client or the backend from scratch, the project stops being a technical task and becomes a prolonged coordination exercise.
The classical approach offers two bad options. The first is to add new path support to the backend — maintaining old endpoints while also writing new ones doubles code complexity and test load. The second is to force clients or partners to migrate to the new path — this is social and operational friction, often requires B2B contract renegotiation, waits for mobile application updates and stretches the transition timeline.
The right model is to introduce a controlled rewriting layer in the request-response flow. This layer converts the path the client sends into the path the backend understands, and if necessary writes the internal paths in the response body back to the external paths the client expects. The backend modernises internally; the client or partner keeps working with the URL scheme it already knows.
For this layer to be effective, three conditions must hold. First, flexible find-and-replace logic: fixed path, prefix substitution, query preservation and FX-based string transformations must all be supported. Second, conditional application: the rule must fire only when the right Host, method, IP, cookie, header or FX condition matches — not on every request. Third, bidirectional mapping with the response body: otherwise the internal links the backend returns become broken URLs on the client side.
TR7 URL and Path Rewriting delivers this model: set_path, set_pathq and normalize_uri actions; FX STRREPLACE / STRREPLACEALL patterns; FX/ACL conditional application; and two-way path mapping via modifyResponse form the foundation of a transparent backend path remap architecture.
TR7's URL rewriting layer builds a controlled bridge between application architecture layers — going well beyond simple path substitution.
An incoming request for `/api/v1/users/123` can be converted to the `/internal/v3/users/123` path the backend expects. set_path changes the path only; set_pathq rewrites path and query string together. The client keeps sending its existing URL while the backend operates on the new architecture.
When a fixed path substitution is not enough, the FX expression language takes over. STRREPLACE and STRREPLACEALL transform specific segments — prefix, suffix or mid-path — inside the path. Operators can compose variables, find-replace fields and conditions within the same rule model.
Every rewriting rule can be scoped with an FX/ACL condition. The rule fires only on a matching Host, method, source IP, cookie, header or FX variable value. Different path transformations with different conditions can run in parallel under the same vService.
Changing the request path alone is often not enough — the backend may return internal paths in the response body. With modifyResponse, HTML links, JSON href fields or any text containing internal paths are written back to the external path format. The result is a fully transparent backend path remap architecture from the client's perspective.
URL path rewriting is not a single action — it is the foundational building block for migration, compatibility and two-way path-hiding patterns.
set_path replaces the path portion of the incoming request with a new path value. The new value can be written statically or made dynamic using smart content variables such as `%HOST`, `%PATH`, `%METHOD` or `%SRCIP`. The query string is not preserved when set_path is used; if query data must be retained, set_pathq is preferred. This action is used to map an old external URL structure to a new internal service layout.
set_pathq manages path and query string in a single rewriting action. Operators can include the existing `%QUERY` value in the new path to preserve the parameters the client sent. New parameters can also be appended — for example, the request `/api/v1/users?id=42` can be transformed to `/internal/v3/users?id=42&version=v3-from-v1`. This is a practical transition mechanism for API versioning and partner compatibility.
normalize_uri normalises the path and URI components to a standard form. Options include merging multiple slashes, stripping dot segments, resolving `../` traversals, decoding safe characters per RFC 3986, uppercasing percent-encoded sequences, handling fragments and sorting query parameters alphabetically. This normalisation is important for cache key consistency, audit readability and resilience against security-bypass attempts. It also helps WAAP and other security controls make decisions on the same canonical path.
STRREPLACE replaces the first match; STRREPLACEALL replaces every match. Operators can write expressions such as `%PATH.STRREPLACE("/old/", "/new/")` to transform specific segments inside the path. This approach handles prefix substitution, mid-path segment replacement and moving legacy URL segments to a new service layout. UI helper fields make entering find and replace values more controlled.
Every path rewriting rule can run conditionally. The condition can be a Host header match, an HTTP method constraint, a source IP range check, a cookie or header value comparison, or any true/false expression produced by the FX engine. Under the same vService, partner-specific, tenant-specific or method-specific path transformations can coexist with different conditions. Requests that do not match continue through the normal flow unaffected.
When set_path or set_pathq converts the request path to an internal path, the backend may return internal paths in the response body. The modifyResponse replace mode writes those internal paths back to the external format. For example: the client requests `/api/v1/orders`, the backend works with `/internal/orders`, and `"href":"/internal/users/42"` in the response JSON is returned as `"href":"/api/v1/users/42"`. The client operates without ever seeing the backend's real URL structure.
modifyResponse is not limited to path remap — it supports different transformations on the response body. The replace mode matches regex or plain-text patterns and substitutes them, making it the primary tool for path remap. The htmlTag mode injects controlled content into HTML tags. The mask mode conceals sensitive data. In the URL and Path Rewriting context, this capability is positioned specifically for bidirectional path mapping.
Path rewriting is applied in the request phase before downstream security controls evaluate the request. This means virtual patching, WAAP signature matching, rate-limiting keys and traffic rules all operate on the rewritten path. The normalised or rearranged path becomes the common input for every subsequent decision layer. The gap between the external URL and the internal service path no longer produces policy inconsistency.
Path transformation must be operationally observable. TR7 can carry the original request path and the rewritten path value into the audit and log stream. On the SIEM side, the question "which path did the client request, which path did the system send to the backend?" becomes answerable. This visibility is critical during migration projects and security reviews.
Multiple path rules can run in sequence under the same vService. The first rule normalises the URI, the second performs a prefix substitution, and the third enriches the query string or appends a suffix under a specific condition. Each rule operates on the output of the previous one. This model enables a readable, testable and incremental transformation chain instead of a single large and risky rule.
URL path rewriting is operated together with smart content variables, FX integration, the condition language, performance characteristics, error behaviour and the response rewriting pattern.
The new path definition can use `%PATH`, `%QUERY`, `%HOST`, `%METHOD`, `%SRCIP`, `%PORT` and custom variables. These variables are composed in the value field of set_path and set_pathq actions to produce a dynamic path. FX functions can be applied to any of these variables.
URL path rewriting is one consumer of the TR7 FX expression engine. Operators do not learn a separate language for path transformation — they use STRREPLACE, STRREPLACEALL and other FX functions within the same expression logic. This shared model provides a consistent management approach across traffic rules, log templates and condition definitions.
FX/ACL conditions narrow the rewriting scope. Expressions such as `%HOST == "partner.example.com"`, `%METHOD in ["POST","PUT"]`, `%SRCIP in MAP_IP("partner_ips")` or `%HEADER("X-Tenant") == "tenant-a"` are all valid. Multiple conditions can be combined with AND / OR logic.
Path rewriting adds low per-request overhead; string-based transformations require no additional socket or file-read operations. STRREPLACE and STRREPLACEALL run in memory. Response body rewriting is more costly because it may require body buffering and regex processing, so it should be used only where path remap scenarios genuinely require it.
If an FX parse error, missing variable or regex mismatch occurs during rewriting, the request can continue through the normal flow via a safe fallback — it is not dropped. The error is written to the audit log so the operator can investigate the configuration problem later. This behaviour protects production access from being interrupted by a misconfigured rule.
The recommended pattern for transparent path remap has two parts: on the request side, the external path is converted to the internal path; on the response side, internal paths in the response body are written back to external paths. These two rules run as a matched pair under the same vService. This pattern becomes the standard structure for API gateway scenarios, B2B partner integrations and monolith-to-microservice migration projects.
Existing clients continue to use `/api/v1/...` endpoints while TR7 converts the request internally to the `/api/v3/...` structure. The v3 links in the response body are written back to v1 format via modifyResponse. The modern backend is activated without any client code changes.
A partner may have used the `/services/payments/...` URL scheme for years while the internal team has moved to `/v2/payment-api/...`. A partner-specific set_path rule scoped to the partner's Host header handles the translation. The partner keeps working with the old URL; the new service architecture runs inside.
A legacy monolith serves `/app/orders`, `/app/users` and `/app/inventory` paths, each of which is being moved to a separate backend service. TR7 applies prefix-based routing and path remap without exposing the split to clients. Users keep the same URL scheme while services are separated in the background.
An attacker may try percent-encoded paths, dot-segment traversals or slash confusion to evade WAAP signature matching. normalize_uri brings the path to canonical form, and subsequent WAAP controls operate on this cleaned value. URL variants that are written differently but target the same resource are evaluated more consistently.
API versioning, B2B partner compatibility and transparent backend path remap — let's walk through a live setup on your own services.