Catchall (Fallback backend)

Document updated on Aug 17, 2023

The catchall endpoint is a particular type of endpoint that, when added, receives all the traffic from routes and methods that do not resolve to any of the other existing endpoints in the configuration.

Its primary use case is for initial stages of a migration, when you want to test a small subset of endpoints on KrakenD and have all the rest of the traffic forwarded to a common backend.

The wildcard endpoints are similar in functionality, but they only listen to a starting path, not everything, and they are a better option.

Catchall configuration

To enable the catchall endpoint, all it takes is to create a regular endpoint with the reserved endpoint name /__catchall.

As with any other endpoint, you must define the url_pattern and the host in its backend section, but in this case, it is acting as the fallback backend. Like this:

{
    "endpoint": "/__catchall",
    "output_encoding": "no-op",
    "input_headers": ["*"],
    "input_query_strings": ["*"],
    "backend": [{
        "encoding": "no-op",
        "url_pattern": "/",
        "host":["http://mybackend:1234"]
    }]
}

The catchall endpoint acts as a reverse proxy and internally works using a no-op endpoint. The route name /__catchall is not registered during startup, it is our convention to mark the fallback route. But effectively it makes little difference for the end-user as all unregistered routes (including /__callback) will fall here anyway.

In connection with working as a no-op endpoint, a few remarks worth noticing:

• You cannot change this endpoint’s output_encoding or encoding. If you do, it will be automatically reverted during startup to no-op and an error log will be shown in the console.
• All query strings and headers sent by the consumer of your API are forwarded to the fallback backend. Regardless of your input_query_strings and input_headers settings, it will revert your settings to behave with a wildcard ["*"], passing everything to the backend.
• As the response is a no-op, the client will get all the headers, encodings, content and status codes of the fallback backend as originally received.
• You can still protect the fallback backend, and you can add authorization, security policies, Lua, plugins, Martian, or any other component of KrakenD that is compatible with no-op.