News KrakenD 2.1 released!

Documentation

Recent changes

You are viewing a previous version of KrakenD Enterprise Edition (v1.3) , go to the latest version

URL Rewrite

The url-rewrite plugin allows you to define a set of URLs or regular expressions that are handled by an endpoint of your choice. In other words, this plugin allows you to declare additional URLs other than the ones defined under the endpoints configuration, used as aliases of existing endpoints.

Extendind router capabilities
This plugin allows you to overcome some of the routing capabilities of KrakenD, such as declaring endpoints that would be conflicting or unaccepted by the KrakenD core.

URL rewrite configuration

You need to define a URL dictionary specifying how requests map to the existing endpoints to use the plugin. There are two diferent ways of declaring rewrites:

  • literal: The literal match takes precedence and is checked first. If the requested URL is exactly the one defined in the map, then the redirection happens.
  • regexp: The regexp expressions are checked in sequence when there are no literal matches. You can use the capturing groups in the endpoint definition.
{
    "version": 2,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
      "github_com/devopsfaith/krakend/transport/http/server/handler": {
        "name": ["url-rewrite", "some-other-plugin-here" ],
        "url-rewrite": {
          "literal": {
            "/hi-there": "/hello",
            "/whatsup": "/hello"
          },
          "regexp": [
            ["/hi-there/([\w\d\s]+)/bar", "/hello/${1}"],
            ["/whats/up/([\w\d\s]+)", "/hey/${1}/whatsup"]
          ]
        }
      }
    }
}

The configuration options inside the url-rewrite plugin are:

  • literal: A map with the exact desired url and its mapping to an endpoint. If the endpoint has {placeholders} you need to write them, but the literal value {placeholders} is passed,
  • regexp: A list of lists, containing the reglar expression that defines the URL to be rewritten, and its endpoint destination. You can use the capturing groups with the syntax ${1}, ${2}, etc.

All regular expressions are evaluated in order. The first matching expression will rewrite and exit.

Older plugin versions (prior to 1.3)

Before KrakenD EE 1.3.0, the url-rewrite dictionary’s content was only literal, meaning that it redirected exact matches only. This was the configuration:

{
    "version": 2,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
      "github_com/devopsfaith/krakend/transport/http/server/handler": {
        "name": ["url-rewrite", "some-other-plugin-here" ],
        "url-rewrite": {
            "/hi-there": "/hello",
            "/whatsup": "/hello"
        }
      }
    }
}

Any request to the URL /hi-there or /whatsup will be redirected to the /hello endpoint with the previous configuration.

Limitations

Mappings are literal. You cannot rewrite URLs that use {placeholders} as part of their URL. The only thing you can do with place holders is a mapping like the following but with a big warning:

"url-rewrite": {
    "/hi-there": "/hello/{subject}"
}

The warning is that you need to be aware that the endpoint will receive the rewrite. Still, it can’t take any value for the {subject} placeholder and will receive the literal {subject} as its value.

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information