URL Rewrite

Overview

The URL Rewrite action allows you to transform the URL path and query parameters of the incoming request to your upstream.

Example

Traffic Policy for rewriting an incoming URL's version and id path params.

YAML

# snippet
---
actions:
  - type: "url-rewrite"
    config:
      format: "ngrok"
      from: "/v1/users/([0-9]+)"
      to: "/v2/users?id=$1"

JSON

// snippet
{
  "actions": [
    {
      "type": "url-rewrite",
      "config": {
        "format": "ngrok",
        "from": "/v1/users/([0-9]+)",
        "to": "/v2/users?id=$1"
      }
    }
  ]
}

Request:

curl https://example.ngrok.app/api/v1/users/42

Result:

> GET https://example.ngrok.app/api/v2/users?id=42 HTTP/1.1

Behavior

When executed, this action will replace all regex matches with the configured replacement. Before regex replacement, all cel expressions will be interpolated and replaced with their corresponding values.

Reference

Supported Directions

• Inbound

Configuration

Type
url-rewrite

Parameter		Description
from	string	A regular expression string to match inside of the URL. Supports interpolating the results of cel expressions outside of regex.
to	string	A regular expression string to replace the from match with. Supports interpolating the results of cel expressions outside of regex.
format	string	(default: ngrok) Determines interpolation format in to/from fields.

Templating Syntax

The results of CEL expressions can be interpolated into your policy's config using ngrok's ${} templating syntax. For a complete list of available variables and functions or to see a more detailed explanation, checkout the docs.

More Examples

Simple variable replacement

YAML

# simple variable replacement
---
actions:
  - type: "url-rewrite"
    config:
      format: "ngrok"
      from: "/api/v1/api?lat=(d+)"
      to: "/api/v2/api?lat=$1&long=86.75309"

JSON

// simple variable replacement
{
  "actions": [
    {
      "type": "url-rewrite",
      "config": {
        "format": "ngrok",
        "from": "/api/v1/api?lat=(d+)",
        "to": "/api/v2/api?lat=$1&long=86.75309"
      }
    }
  ]
}

Request:

curl https://example.ngrok.app/api/v1?lat=42.42

Result:

• Path and params rewritten on incoming request

# Url on incoming request to upstream
> GET https://example.ngrok.app/api/v2?lat=42&long=86.75309 HTTP/2

---

YAML

# regex and cel expressions
---
actions:
  - type: "url-rewrite"
    config:
      format: "ngrok"
      from: "/api/v1/(carmen)/sandiego?city=${conn.geo.city}"
      to: "/api/v2/$1/sandiego?found=${conn.geo.city}"

JSON

// regex and cel expressions
{
  "actions": [
    {
      "type": "url-rewrite",
      "config": {
        "format": "ngrok",
        "from": "/api/v1/(carmen)/sandiego?city=${conn.geo.city}",
        "to": "/api/v2/$1/sandiego?found=${conn.geo.city}"
      }
    }
  ]
}

Request:

curl https://example.ngrok.app/api/v1/api/carmen/sandiego?city=salt-lake-city

Result:

• Url rewritten on incoming request

# New Url on incoming request to upstream
> GET https://example.ngrok.app/api/v2/carmen/sandiego?found=boulder HTTP/2

---

YAML

# variable replacement on path params
---
actions:
  - type: "url-rewrite"
    config:
      format: "ngrok"
      from: "?now=false"
      to: "?now=${conn.ts.start < time.now}"

JSON

// variable replacement on path params
{
  "actions": [
    {
      "type": "url-rewrite",
      "config": {
        "format": "ngrok",
        "from": "?now=false",
        "to": "?now=${conn.ts.start < time.now}"
      }
    }
  ]
}

Request:

curl https://example.ngrok.app/api/v1?now=false

Result:

• Url Rewritten on incoming request

> GET https://example.ngrok.app/api/v2?now=true HTTP/2

---

Action Result Variables

The following variables are available following the invocation of this action.

Name	Type	Description
actions.ngrok.url_rewrite.matches	[]string	The list of matched elements.
actions.ngrok.url_rewrite.url	string	The resulting URL after it was re-written.
actions.ngrok.url_rewrite.error.code	string	Code for an error that occurred during the invocation of an action.
actions.ngrok.url_rewrite.error.message	string	Message for an error that occurred during the invocation of an action.