Endpoint Configuration

Document updated on Jan 28, 2021

KrakenD endpoints are the most critical configuration part of KrakenD as they are what your end users consume. By adding endpoint objects, you create the API contract your users will consume.

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.mybackend.com"
          ]
        }
      ]
    }
  ]
}

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

Inside this object, you can add manipulation options and transform the response before its returned to the end-user.

Endpoint configuration

The endpoint object accepts the following attributes. As you can see, most of them are optional:

• endpoint: The exact string resource URL you want to expose. You can use {placeholders} to use variables when needed. URLs do not support colons : in their definition.
• backend: List of all the backend objects queried for this endpoint.
• method (optional): Must be written in uppercase GET, POST, PUT, PATCH, DELETE. Defaults to GET.
• output_encoding (optional): See the supported encodings. Defaults to json.
• extra_config (optional): Configuration of components and middlewares that are executed with this endpoint.
• input_query_strings (optional): Recognized GET parameters. See parameter forwarding.
• input_headers (optional): Forwarded headers. See headers forwarding.
• concurrent_calls (optional): A technique to improve response times. See concurrent requests
• cache_ttl (optional): (time unit) The cache headers informing for how long the CDN can cache the request to this endpoint. Related: caching backend responses.
• timeout (optional): (time unit) Maximum time you’ll wait for the slowest backend response. Usually specified in seconds (s) or milliseconds (ms. E.g: 2000ms or 2s)

* Valid time units are: ns, us, (or µs), ms, s, m, h E.g: 1s

Endpoints with multiple nesting levels

You might have envisioned KrakenD as a proxy and expected its endpoint declaration works as a prefix and listens 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 and "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 declare all possible endpoints: /user/{id}, /user/{id}/{level2}, /user/{id}/{level2}/{level3}, etc.
2. You use a Wildcard (Enterprise only)

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 will need to 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.mybackend.com"
          ]
        }
      ]
    },
    {
      "endpoint": "/v1/users/{user}",
      "method": "POST",
      "backend": [
        {
          "url_pattern": "/users/summary/{user}",
          "method": "POST",
          "host": [
            "https://api.mybackend.com"
          ]
        }
      ]
    }

  ]
}

Endpoint variables

As you can see in the examples above, endpoints can define variables in its 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 accept a request like /user/1/2, as there is an extra slash than the definition, and KrakenD considers this to be a different endpoint.