Skip to main content

URL Rewrite Handler

The URL Rewrite handler can be used to proxy and rewrite requests to a different API without writing any code. The handler allows mapping request data and parameters to a URL on another host. You can also combine the URL rewrite handler with policies such as the Change Method Inbound policy to modify virtually any aspect of your request.

Setup via Portal​

The Rewrite Handler can be added to any route using the Route Designer. Open the Route Designer by navigating to the Code Editor tab then clicking routes.json. Inside of any route, select URL Rewrite from the Request Handlers drop down.

Url Rewrite Handler selection

In the text box enter the URL to rewrite the request. Values can be mixed into the URL string using Javascript string interpolation syntax. For example:

https://echo.zuplo.io/${method}/${params.productId}

The following objects are available for substitution:

  • request: ZuploRequest - the full ZuploRequest object
  • params: Record<string, string> - The parameters of the route. For example, params.productId would be the value of :productId in a route.
  • query: Record<string, string> - The query parameters of the route. For example, query.filterBy would be the value of ?filterBy=VALUE.
  • headers: Headers - the incoming request's headers object
  • url: string - The full incoming request as a string
  • host: string - The host portion of the incoming url
  • hostname: string - The hostname portion of the incoming url
  • pathname: string - The pathname portion of the incoming url
  • port: string - The port portion of the incoming url
  • search - The search portion of the incoming url

Use the following methods to encode portions of the URL:

  • encodeURIComponent: The encodeURIComponent() function encodes a URI by replacing each instance of certain characters with escape sequences.
  • e: An alias to encodeURIComponent to help keep urls more readable. Can be used like ${e(params.productId)}

Example Values​

A few examples of the values of various substitutions.

  • ${headers.get("content-type")} - "application/json"
  • ${host} - "example.com:8080"
  • ${hostname} - "example.com"
  • ${method} - "GET"
  • ${origin} - "https://example.com"
  • ${params.productId} - ":productId"
  • ${pathname} - "/v1/products/:productId"
  • ${port} - "8080"
  • ${protocol} - "https:"
  • ${query.category} - "cars"
  • ${search} - "?category=cars"
  • ${url} - "https://example.com:8080/v1/products/:productId?category=cars"

Setup via Routes.json​

The URL Rewrite handler can also be added manually to the routes.json file with the following route configuration.

{
  "label": "Welcome",
  "path": "/",
  "methods": ["GET"],
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "urlRewriteHandler",
    "options": {
      "rewritePattern": "https://welcome.zuplo.io"
    }
  },
  "corsPolicy": "anything-goes",
  "version": "none",
  "summary": "Proxy Welcome API",
  "description": "This Route will proxy the welcome.zuplo.io api"
}