UriPathRewriteFilter

Rewrite a URL path, using a bidirectional mapping:

  • In the request flow, fromPath is mapped to toPath.

  • In the response flow, toPath is mapped to fromPath.

If the response includes a Location or Content-Location header with toPath in its URL, the response is rewritten with fromPath.

Usage

{
  "name": string,
  "type": "UriPathRewriteFilter",
  "config": {
    "mappings": configuration object,
    "failureHandler": Handler reference
  }
}

Properties

"mappings": configuration object, required

One or more bidirectional mappings between URL paths:

{
  "mappings": {
    "/fromPath1": "/toPath1",
    "/fromPath2": "/toPath2"
  }
}

The incoming URL must start with the mapping path. When more than one mapping applies to a URL, the most specific mapping is used. Duplicate fromPath values are removed without warning. The following table illustrates mapping:

Examples of URL Path Rewriting
Mappings Original URL to rewritten URL

"/external": "/internal" "/external/forge": "/internal/rock"

http://openig.example.com:8080/external Rewritten to http://openig.example.com:8080/internal

http://openig.example.com:8080/external/forge Rewritten to http://openig.example.com:8080/internal/rock

http://openig.example.com:8080/forge Not rewritten

"failureHandler": handler reference, optional

Failure handler to be invoked if an invalid URL is produced when the request path is mapped or when the response Location or Content-Location header URI path is reverse-mapped.

Provide an inline handler declaration, or the name of a handler object defined in the heap. See also Handlers.

Default: HTTP 500

Example

This example changes a request URL as follows:

  • The baseURI overrides the scheme, host, and port of a request URL.

  • The UriPathRewriteFilter remaps the path of a request URL.

    Requests to http://openig.example.com:8080/mylogin are mapped to http://app.example.com:8081/login.

    Requests to http://openig.example.com:8080/welcome are mapped to http://app.example.com:8081/home.

    Requests to http://openig.example.com:8080/other are mapped to http://app.example.com:8081/not-found, and result in an HTTP 404.

    Requests to http://openig.example.com:8080/badurl are mapped to the invalid URL http://app.example.com:8081[, and invoke the failure handler.

{
  "name": "UriPathRewriteFilter",
  "baseURI": "http://app.example.com:8081",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "UriPathRewriteFilter",
          "config": {
            "mappings": {
              "/mylogin": "/login",
              "/welcome": "/home",
              "/other": "/not-found",
              "/badurl": "["
            },
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "status": 500,
                "headers": {
                  "Content-Type": [
                    "text/plain"
                  ]
                },
                "entity": "Invalid URL produced"
              }
            }
          }
        }
      ],
      "handler": "ClientHandler"
    }
  }
}