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.

• If requests match... 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.

• If requests match... 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.

• If requests match... 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.

• If requests match... ends_with(http.request.uri.path, ".css")

• Rewrite configuration:

  Rewrite object: Query string

  Operation method: Dynamic

  Expression: regex_replace(http.request.uri.query, ".*", "")

• 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/.

• If requests match... (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

• If requests match... 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.

• If requests match... 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.

• If requests match... 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

Example 10: Exclude requests by file name extension and rewrite

• Use case: Exclude requests whose file name extension is html, and rewrite all other requests to a specified path.

• If requests match... File name extension not equal to html. Expression: http.request.uri.path.extension ne html

• Rewrite configuration:

  Rewrite object: Path

  Operation method: Static

  Rewritten path: /static/index.html

Example 11: Route requests based on file name extension

• Use case: Route requests that have a file name extension to static/url, and route requests that have no file name extension to static/index.html.

• If requests match... and rewrite configuration:

  • For requests with a file name extension, use the match condition http.request.uri.path.extension ne "".

    Rewrite object: Path

    Operation method: Static

    Rewritten path: /static/url

  • For requests without a file name extension, use the match condition http.request.uri.path.extension eq "".

    Rewrite object: Path

    Operation method: Static

    Rewritten path: static/index.html

Reference documents

For more information about expression syntax, see the Characteristics of rule-based features.

Expression reference