Rewrite URL

Execution flow

1. Check cache: The edge node looks up the cache by the original URL. On a cache miss, URL rewrite rules transform the URL to the target path.

2. Origin request: The rewritten URL is sent to the origin server. The response is cached under the original URL as the cache key.

3. Return cached content: The cached content is returned to the client.

Execution order

URL rewrite runs after the cache check and origin selection, but before origin request header modification. The path is adjusted after the origin target is determined without affecting header processing.

Example 1: Origin path migration

• Use case: The origin moves images from the /images/ directory to the /static/img/ directory.

• Match condition: starts_with(http.request.uri.path, "/images/")

• Rewrite configuration:

  Rewrite object: Path

  Operation method: Dynamic

  Expression: regex_replace(http.request.uri.path, "^/images/", "/static/img/")

• Rewrite effect:

  User request: https://example.com/images/logo.png

  Origin request: https://origin.com/static/img/logo.png

Example 2: API version adaptation

• Use case: Rewrite requests from /api/v1/ to /api/v2/ during origin requests and append a version identifier.

• Match condition: starts_with(http.request.uri.path, "/api/v1/")

• Rewrite configuration:

  Rewrite object: Path, Query string

  Operation method: Dynamic

  Path rewrite expression: regex_replace(http.request.uri.path, "^/api/v1/", "/api/v2/")

  Query string rewrite expression: concat("api_version=v2&", http.request.uri.query)

• Rewrite effect:

  User request: https://example.com/api/v1/users?limit=10

  Origin request: https://origin.com/api/v2/users?api_version=v2&limit=10

Example 3: Parameter standardization

• Use case: Different clients use different parameter names (such as userid and uid). Unify them to the standard user_id.

• Match condition: http.request.uri.query contains "userid="

• Rewrite configuration:

  Rewrite object: Query string

  Operation method: Dynamic

  Expression: regex_replace(http.request.uri.query, "userid=", "user_id=")

• Rewrite effect:

  User request: https://example.com/profile?userid=123

  Origin request: https://origin.com/profile?user_id=123

Example 4: Path normalization

Example 5: Remove all query parameters

• Use case: Strip all query parameters from static resources. For example, remove query strings from URIs ending with .css.

• Match condition: ends_with(http.request.uri.path, ".css")

• Rewrite configuration:

  Rewrite object: Query string

  Operation method: Static, leave empty

• Rewrite effect:

  User request: https://example.com/style.css?version=1.2.3

  Origin request: https://origin.com/style.css

Example 6: Simplify dynamic paths

• Use case: Remove redundant number sequences from paths. For example, strip 123 followed by digits from paths under /example/.

• Match condition: (http.request.uri matches "^/example/(.*)123[0-9]+(.*)$")

• Rewrite configuration:

  Rewrite object: Path

  Operation method: Dynamic

  Expression: regex_replace(http.request.uri,"^/example/(.*)123[0-9]+(.*)$","/example/$1$2")

• Rewrite effect:

  User request: https://example.com/example/tool12300341features

  Origin request: https://origin.com/example/toolfeatures

Example 7: Extract path parameters and add to query string

• Use case: Extract a dynamic path segment, append it as a query parameter, and replace it with a fixed string:

  Original URI: /api/v1/dynamic_value/download?version=1&size=2

  Rewritten URI: /api/v1/fixed/download?version=1&size=2&token=dynamic_value

• Match condition: All incoming requests

• Rewrite configuration:

  Rewrite object: Path + Query string

  Operation method: Dynamic

  Path rewrite expression: regex_replace(http.request.uri.path, "^/api/v1/(.*)/download$", "/api/v1/fixed/download")

  Query string rewrite expression: concat(http.request.uri.query,"&token=",regex_replace(http.request.uri.path, "^/api/v1/(.*)/download$","$1"))

• Rewrite effect:

  User request: https://example.com/api/v1/ABC123/download?version=1&size=2

  Origin request: https://origin.com/api/v1/fixed/download?version=1&size=2&token=ABC123

Example 8: Remove specific parameters

• Use case: Remove specific query parameters. For example, given https://example.com/1.txt?key1=value1&key2=value2&key3=value3&key4=value4&key5=value5&key6=value6, remove key2, key3, key5, and key6, keeping only key1 and key4.

• Match condition: All incoming requests

• Rewrite configuration:

  Rewrite object: Query string

  Operation method: Dynamic

  Expression: regex_replace(regex_replace(regex_replace(regex_replace(http.request.uri.query, "(&?key2=[^&]*)", ""), "(&?key3=[^&]*)", ""), "(&?key5=[^&]*)", ""), "(&?key6=[^&]*)", "")

  Note

  Each nested regex_replace removes one parameter. The pattern (&?keyN=[^&]*) matches the preceding & to prevent leftover & characters.

• Rewrite effect:

  User request: https://example.com/1.txt?key1=value1&key2=value2&key3=value3&key4=value4&key5=value5&key6=value6

  Origin request: https://origin.com/1.txt?key1=value1&key4=value4

Example 9: Keep specific parameters

• Use case: Keep only specific query parameters. For example, given https://example.com/1.txt?key1=value1&key2=value2&key3=value3&key4=value4, keep only key1 and key4.

• Match condition: All incoming requests

• Rewrite configuration:

  Rewrite object: Query string

  Operation method: Dynamic

  Expression: concat("key1=", http.request.uri.args["key1"], "&key4=", http.request.uri.args["key4"])

  Note

  The concat function rebuilds the query string with only the specified parameters. Use http.request.uri.args["keyN"] to extract each parameter value. Unlisted parameters are excluded.

• Rewrite effect:

  User request: https://example.com/1.txt?key1=value1&key2=value2&key3=value3&key4=value4

  Origin request: https://origin.com/1.txt?key1=value1&key4=value4

Reference documents

For more information about expression syntax, see the Rule characteristics.

Expression reference