Case Study Jobteaser Case Study: Scalable Public APIs with KrakenD

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

Document updated on May 3, 2023

Wildcard Endpoints in KrakenD API Gateway

The wildcard functionality allows you to declare endpoints that have many implicit paths in their backend. Instead of declaring all possible routes one by one, you can create one or more endpoints that will respond to a path pattern instead. The gateway then forwards all routes starting with the configured path to the backend(s).

For instance, you can declare an endpoint /foo/* that forwards all traffic starting with /foo/ to a specific backend. When a user calls /foo/bar or /foo/bar/vaz, the request is processed by the same endpoint and backends.

Since paths are implicit, KrakenD does not know if a request is valid or not beyond checking that the pattern is correct, or checking additional components you might add. Therefore, everything it can do is to “hope for the best” before routing the request, and it is the responsibility of the backend to determine if the path is valid.

Wildcard endpoints

The wildcard functionality is a good candidate when you are in a migration scenario and you need to expose a lot of endpoints quickly. However, it would be best to transition to an explicit declaration instead, and you should aim for it if security is a concern.

Implicit declaration is less secure
Please make explicit declarations (define all endpoints) whenever possible. Using a wildcard opens the door to exposing endpoints you are unaware of, allowing end-users to experiment with the URLs, scan your backend services, or exploit “zombie endpoints” that were originally published and forgotten over time.

Wildcard configuration

To enable wildcards, you only need to write a string ending in /* in the’ endpoint’ path. Then, the receiving backend will automatically append the remaining request to its url_pattern. For instance, given the following configuration:

{
    "endpoint": "/v1/*",
    "backend": [{
        "host": ["http://legacy-api"],
        "url_pattern": "/"
    }]

}

When requesting to http://krakend/v1/hello, you get a request to your backend ashttp://legacy-api/hello. Notice that you don’t need to write any asterisk in the url_pattern.

The wildcard applies to the path only. If you want to use multiple methods (GET, PUT, POST, etc.), you still need to create an entry per method as in any other KrakenD endpoint.

Wildcard Limitations

Make sure to declare wildcards per the following rules:

  • You cannot use multiple asterisks (e.g.: /v1/*/foo/*). Instead, use {placeholders}. E.g., /v1/{service}/foo/*.
  • You cannot route all traffic on the root level (e.g., "endpoint": "/*"). Therefore, you must declare at least one directory level before placing the wildcard. See the Catch-All endpoint for such uses.
  • You cannot declare colliding paths. For instance if you have an endpoint /v1/foo you cannot create a wildcard /v1/* (although you can do this with the old plugin, see documentation below)

Examples of valid paths:

  • /a/b/c/*
  • /a/*
  • /{var}/*
  • /{foo}/{bar}/*

Examples of invalid paths:

  • /abc* (doesn’t end in /*)
  • /* (forwards all traffic, use Catch-All instead)
  • /*/a/* (multiple uses of *)

As you can see, combining the wildcard with endpoint variables is possible. For instance, you could have the following paths configured:

{
    "endpoints": [
        {
            "endpoint": "/v1/{service}/*",
            "backend": [{
                "url_pattern": "/v1/{service}/"
            }]
        },
        {
            "endpoint": "/{owmamma}/*",
            "backend": [{
                "url_pattern": "/{owmamma}/"
            }]
        }
    ]
}

Upgrading from the old wildcard plugin (before v2.3)

If you used Wildcards before EE v2.3, eliminate now all entries referring to plugins. This means:

  • If you don’t use additional plugins, you can get rid of the plugin entry in the root level.
  • You can delete all plugin/http-server objects if they only use the wildcard
  • You can delete any wildcard object in the configuration
  • You can delete all plugin/http-client with an insider wildcard entry.
  • You can delete all "X-Krakend-Wildcard" entries in input_headers.

For instance, if you had this configuration:

{
    "version": 3,
    "port": 8080,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": [ "wildcard" ],
            "wildcard": {
                "endpoints": {
                    "/__wildcard/foo": [ "/foo" ],
                    "/__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"
                    }
                }
            }
            ]
        }
    ]
}

Since EE 2.3, it has become:

{
    "version": 3,
    "port": 8080,
    "endpoints": [
       {
            "endpoint": "/foo/*",
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/"
            }
            ]
        },
        {
            "endpoint": "/v1/*",
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/"
            }
            ]
        }
    ]
}
Scarf

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.

See all support channels