Wildcard routes

Document updated on Mar 23, 2021

The wildcard plugin allows you that URLs starting with known patterns forward to a common endpoint without declaring all possible routes. For instance, you want to forward all traffic to /foo/* (plus any nesting levels) to a specific backend.

Let’s say you define the wildcard pattern /foo. It will react to URLs like /foo, /foo/a?x=1, /foo/a/b/c/d, /foo/*, etc. But /foobar won’t work as /foobar is not a subresource of /foo.

Wildcard definitions are not regexp patterns but literal matches of a path (and all its subresources).

The receiving endpoint receives the request in its url_pattern appending everything after the declared wildcard pattern.

Wildcard configuration

When using this plugin, you need to provide two things:

1. The paths that are wildcards (e.g.: /foo), defined in the plugin/http-server section.
2. The receiving endpoints used as the processors of all wildcard traffic (e.g.,/__wildcard/foo), defined in the plugin/http-client section.

We recommend using a specific endpoint prefix so it’s clear to everyone that the endpoint is internal and used for this purpose. In our sample configurations, we use /__wildcard/ as a prefix. Hence, it becomes evident when reading the configuration what it is for, but using /__wildcard/ is not mandatory, and you can use whatever you want or no prefix at all.

If you want to use multiple methods (PUT, POST, etc.) you will need to create an entry per method as in any other KrakenD endpoint.

The two required blocks of configuration mentioned above are:

1. Wildcard HTTP server plugin

Defines which requests are considered a wildcard and where the traffic is sent to:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": [ "wildcard" ],
            "wildcard": {
                "endpoints": {
                    "/__wildcard/foo": [ "/foo", "/aliasfoo" ]
                }
            }
        }
    }
}

The wildcard plugin has only one configuration map:

• endpoints (map): The key of the map is the KrakenD endpoint that receives all the wildcard traffic. The value is an array with all the user paths that match this wildcard (you don’t need to declare the subresources).

2. Wildcard HTTP client plugin

The second block is the HTTP client plugin that enables an endpoint for wildcard processing and appends the full path to the url_pattern. When a user sends a request to /foo/a/b/c the client part appends /a/b/c to the url_pattern you have defined.

{
    "endpoint": "/__wildcard/the-foo",
    "input_headers": [ "X-Krakend-Wildcard" ],
    "backend": [
    {
        "host": [ "http://localhost:8080" ],
        "url_pattern": "/__debug/foo",
        "extra_config": {
            "plugin/http-client": {
                "name": "wildcard"
            }
        }
    }
    ]
}

• Include "input_headers": [ "X-Krakend-Wildcard" ] in the endpoint definition as it is the internal mechanism used to identidy wildcards. These headers only live inside KrakenD.
• Include an extra_config with the plugin/http-client named wildcard

Configuration of wildcards

A full example of wildcard configuration is below. KrakenD will take requests like /foo/* and /aliasfoo/* and send them to the KrakenD endpoint /__wildcard/the-foo. All requests to /v1/*will be sent to the /__wildcard/legacy endpoint. Highlighting relevant blocks:

{
    "version": 3,
    "port": 8080,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": [ "wildcard" ],
            "wildcard": {
                "endpoints": {
                    "/__wildcard/foo": [ "/foo", "/aliasfoo" ],
                    "/__wildcard/legacy": [ "/v1" ]
                }
            }
        }
    },
    "endpoints": [
       {
            "endpoint": "/__wildcard/foo",
            "input_headers": [ "X-Krakend-Wildcard" ],
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/foo",
                "extra_config": {
                    "plugin/http-client": {
                        "name": "wildcard"
                    }
                }
            }
            ]
        },
        {
            "endpoint": "/__wildcard/legacy",
            "input_headers": [ "X-Krakend-Wildcard" ],
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/legacy",
                "extra_config": {
                    "plugin/http-client": {
                        "name": "wildcard"
                    }
                }
            }
            ]
        }
    ]
}