News KrakenD EE v2.9 released: Redis Cluster Support, LRU, WebSockets Upgrades & More!

Document updated on Dec 12, 2024

Endpoint Configuration

KrakenD endpoints are the most critical configuration part of KrakenD, as they are what your end users consume. Adding endpoint objects creates the API contract your users will consume.

Configuration overview
If you are still getting familiar with KrakenD’s configuration structure, take a moment to read Understanding the configuration file.

The endpoints array contains the API definition you are publishing. It is a collection of endpoint objects, and you have to place it at the root of your configuration file.

The endpoint object

To create an endpoint, you only need to add an endpoint object under the endpoints collection. An endpoint object should contain at least the endpoint name and a backend section (to where it connects to). The defaults are taken if no further information is declared (e.g., method will be a GET, and output_encoding as json).

An endpoints section might look like this:

{
  "endpoints": [
    {
      "endpoint": "/v1/users/{user}",
      "method": "GET",
      "backend": [
        {
          "url_pattern": "/users/summary/{user}",
          "method": "GET",
          "host": [
            "https://api.example.com"
          ]
        }
      ]
    }
  ]
}

The previous example exposes a GET /v1/users/{user} endpoint to the clients and takes the data from your existing backend GET https://api.example.com/users/summary/{user}.

Inside this object, you can add manipulation options and transform the response before it returns to the end user.

Endpoint object configuration

The configuration attributes of endpoints objects are:

Fields of Endpoint Object
* required fields

backend * array
List of all the backend objects queried for this endpoint
cache_ttl
Sets or overrides the cache headers to inform for how long the client or CDN can cache the request to this endpoint. Setting this value to a zero-value will use the cache_ttl of the service if any. Related: caching backend responses.
Specify units using ns (nanoseconds), us or µs (microseconds), ms (milliseconds), s (seconds), m (minutes), or h (hours).
concurrent_calls integer
The concurrent requests are an excellent technique to improve the response times and decrease error rates by requesting in parallel the same information multiple times. Yes, you make the same request to several backends instead of asking to just one. When the first backend returns the information, the remaining requests are canceled.
Defaults to 1
endpoint * string
The path of the URL you want to expose. The path is case-sensitive and should start with a slash /. You can use {placeholders} to allow dynamic variables. For example: /foo/{var}/baz. You can also add an ending /* in the path to enable wildcards (Enterprise only..

The router will try to automatically redirect calls to endpoints with an incorrect case or incorrect trailing slash to its correct version offering a 301. There are no guarantees that it will succeed and the request might even fail completely while trying (and log an ugly error with a trace). The safest option is to disable automatic redirections by setting to true the flags disable_redirect_fixed_path and disable_redirect_trailing_slash in the router options.

Limitations: URLs do not support colons : in their definition. All {vars} are meant to be isolated in the path and not to be used to build words, like in /file.{ext} See disable_rest for that usage.
Examples: "/new-endpoint" , "/foo/{var}" , "/foo/{var1}/{var2}"
extra_config object
Configuration entries for additional components that are executed within this endpoint, during the request, response or merge operations.
input_headers array
Defines the list of all headers allowed to reach the backend when passed.

By default, KrakenD won’t pass any header from the client to the backend. This list is case-insensitive. You can declare headers in lowercase, uppercase, or mixed.

An entry ["Cookie"] forwards all cookies, and a single star element ["*"] as value forwards everything to the backend (it’s safer to avoid this option), including cookies. See headers forwarding
Defaults to []
input_query_strings array
Defines the exact list of quey strings parameters that are allowed to reach the backend. This list is case-sensitive.

By default, KrakenD won’t pass any query string to the backend.

A single star element ["*"] as value forwards everything to the backend (it’s safer to avoid this option)
Defaults to []
method
The method supported by this endpoint. Create multiple endpoint entries if you need different methods.
Possible values are: "GET" , "POST" , "PUT" , "PATCH" , "DELETE"
Defaults to "GET"
output_encoding
The gateway can work with several content types, even allowing your clients to choose how to consume the content. See the supported encodings
Possible values are: "json" , "json-collection" , "yaml" , "fast-json" , "xml" , "negotiate" , "string" , "no-op"
Defaults to "json"
timeout string
The duration you write in the timeout represents the whole duration of the pipe, so it counts the time all your backends take to respond and the processing of all the components involved in the endpoint (the request, fetching data, manipulation, etc.). Usually specified in seconds (s) or milliseconds (ms. e.g.: 2000ms or 2s). If you don’t set any timeout, the timeout is taken from the entry in the service level, or to the system’s default
Specify units using ns (nanoseconds), us or µs (microseconds), ms (milliseconds), s (seconds), m (minutes), or h (hours).
Examples: "2s" , "1500ms"
Defaults to "2s"

Endpoints with multiple nesting levels

You might have envisioned KrakenD as a proxy and expected its endpoint declaration to work as a prefix and listen to any path with an undetermined number of nesting levels. But KrakenD does not work like this by default. Instead, it expects you to declare every possible URL structure.

For instance, you declared an "endpoint": "/user/{id}" and you expected to resolve URLs like /user/john/profile/preferences, but you are getting a 404 instead. There are two solutions to this problem:

  1. You can declare all possible endpoints: /user/{id}, /user/{id}/{level2}, /user/{id}/{level2}/{level3}, etc.
  2. You use a Wildcard Enterprise

Endpoints listening to multiple methods

The method attribute defines the HTTP verb you can use with the endpoint. If you need to support multiple methods (e.g., GET, POST, DELETE) in the same endpoint, you must declare one endpoint object for each method. So if you want the same endpoint to listen to GET and POST requests, you need the following configuration:

{
  "endpoints": [
    {
      "endpoint": "/v1/users/{user}",
      "method": "GET",
      "backend": [
        {
          "url_pattern": "/users/summary/{user}",
          "method": "GET",
          "host": [
            "https://api.example.com"
          ]
        }
      ]
    },
    {
      "endpoint": "/v1/users/{user}",
      "method": "POST",
      "backend": [
        {
          "url_pattern": "/users/summary/{user}",
          "method": "POST",
          "host": [
            "https://api.example.com"
          ]
        }
      ]
    }

  ]
}
Notice that the method is declared both in the endpoint and in the backend (as they could be different).

Endpoint variables

As you can see in the examples above, endpoints can define variables in their endpoint definition. To do so, encapsulate the variable name with curly braces, like {var}.

{
  "endpoint": "/user/{id}"
}

The previous endpoint will accept requests like /user/123 or /user/A-B-C. But it won’t take a request like /user/1/2, as there is an extra slash than the definition, and KrakenD considers this to be a different endpoint.

Router rules to avoid collisions

When you declare multiple endpoints that share common prefixes, make sure that you do not declare the same route with different variable names.

For instance, you cannot have the following two endpoints coexisting:

  • endpoint: /user/{userid}
  • endpoint: /user/{iduser}/some

This will cause a panic on startup (that you can catch earlier if you run a krakend check -t -c krakend.json )

But you can have the same routes declared as:

  • endpoint: /user/{userid}
  • endpoint: /user/{userid}/some

And this will work.

Similarly you can’t do this:

  • endpoint: /v1/{domain}/user/{userid}
  • endpoint: /v1/{domain}/user/{iduser}/some

But you can declare the same route as:

  • endpoint: /v1/{domain}/user/{userid}
  • endpoint: /v1/{domain}/user/{userid}/some

Summarizing, on colliding routes, make sure to use the same variable names.

Disable RESTful checking

By default KrakenD only works with RESTful URL patterns in its endpoint definition. Enable the option disable_rest in the root of your configuration if need unrestful endpoints, e.g.: /file.{extension}

{
  "$schema": "https://www.krakend.io/schema/v2.9/krakend.json",
  "version": 3,
  "disable_rest": true,
  "endpoints": [
    {
      "endpoint": "/foo/{var}/file.{extension}",
      "backend": [
        {
          "host": [
            "http://example.com"
          ],
          "url_pattern": "/{var}.{extension}"
        }
      ]
    }
  ]
}

Automatic protocol and encoding translation

The endpoints return HTTP content to the end-user in any of the supported encodings, regardless of the type of backend you are connecting to.

If, for instance, one of the backends you are connecting to uses AMQP, Kafka, gRPC, or any other supported services, KrakenD will perform automatically for you both the protocol and the encoding translation.

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