News KrakenD 2.1.1 Enterprise released - Now with ARM64 support

Documentation

Recent changes

Declaring and connecting to backends

The concept of backend refers to the origin servers providing the necessary data to populate your endpoints. A backend can be something like your HTTP-based API, a Lambda function, or a Kafka queue, for example.

A backend can be any server inside or outside your network if it is reachable by KrakenD. For instance, you can create endpoints fetching data from your internal servers and enrich them by adding third-party data from an external API like Github, Facebook, or other services. You can also return everything aggregated in a single glorified response.

A backend object is an array of all the services that an endpoint connects to. It defines the list of hostnames connected to and the URL to send or receive the data.

When a KrakenD endpoint is hit, the engine requests all defined backends in parallel (unless a sequential proxy is used, or you use no-op encoding). The returned content is parsed according to its encoding or in some cases itsextra_config configuration.

Multiple non-safe methods

Even though you can use several backends in one endpoint, KrakenD does not allow you to define multiple non-safe (write) backends. This is a (sometimes controversial) design decision to disable the gateway to handle transactions.

If you need to have a write method (POST, PUT, DELETE, PATCH) together with other GET methods, use the sequential proxy and place a maximum of 1 write method at the end of the sequence.

Backend/Upstream configuration

Inside the backend array, you need to create an object for each upstream service used by its declaring endpoint. The combination of host + url_patternset the full URL that KrakenD will use to fetch your upstream services. Most of the backends will require a simple configuration like:

{
    "host": ["http://your-api"],
    "url_pattern": "/url"
}

All the options relative to the backend definition are:

allow

array
Only return the fields in the list. Only the matching fields (case-sensitive) are returned in the final response. Use a dot . separator to define nested attributes, e.g.: a.b removes {"a":{"b": true}}
deny

array
Don’t return the fields in the list. All matching fields (case-sensitive) defined in the list, are removed from the response. Use a dot . separator to definr nested attributes, e.g.: a.b removes {"a":{"b": true}}.
disable_host_sanitize

boolean
Set it to true when the host doesn’t need to be checked for an HTTP protocol. This is the case of sd=dns or when using other protocols like amqp://, nats://, kafka://, etc. When set to true, and the protocol is not HTTP, KrakenD fails with an invalid host error.
Defaults to false
encoding

string
Defines your needed encoding to set how to parse the response. Defaults to the value of its endpoint’s encoding, or to json if not defined anywhere else.
Possible values are: json , safejson , fast-json , xml , rss , string , no-op
Defaults to "json"
extra_config

object
When there is additional configuration related to a specific component or middleware (like a circuit breaker, rate limit, etc.), it is declared under this section.
group

string
Instead of placing all the response attributes in the root of the response, create a new key and encapsulate the response inside.
Defaults to "backend1"
host

array
An array with all the available hosts to load balance requests, including the schema (when possible) schema://host:port. E.g.: https://my.users-ms.com. If you are in a platform where hosts or services are balanced (e.g., a K8S service), write a single entry in the array with the service name/balancer address. Defaults to the host declaration at the configuration’s root level, and the service fails starting when there is none.
is_collection

boolean
Set to true when your API does not return an object {} but a collection []
Defaults to true
mapping

object
Mapping, or also known as renaming, let you change the name of the fields of the generated responses, so your composed response would be as close to your use case as possible without changing a line on any backend.
method

string
The method sent to this backend in uppercase. The method does not need to match the endpoint’s method. When the value is omitted, it uses the same endpoint’s method.
Possible values are: GET , POST , PUT , PATCH , DELETE
Defaults to "GET"
sd

string
The Service Discovery system to resolve your backend services. Defaults to static (no external Service Discovery). Use dns to use DNS SRV records.
Possible values are: static , dns
Defaults to "static"
target

string
Removes the matching object from the reponse and returns only its contents.
url_pattern *

string
The path inside the service (no protocol, no host, no method). E.g: /users. Some functionalities under extra_config might drop the requirement of declaring a valid url_pattern, but they are exceptions. The URL must be RESTful, if it is not (e.g.: /url.{some_variable}.json), then see how to disable RESTful checking.

* indicates a required field. Parameters in alphabetical order.

Other configuration options such as the ones for data manipulation are available. You will find them in each specific feature section.

Backend configuration example

In the example below, KrakenD offers an endpoint /v1/products that merges the content from two different services using the URLs /products and /offers. The marketing (marketing.myapi.com) and the products (products-XX.myapi.com) API requests are fired simultaneously. KrakenD will load-balance among the listed hosts (here or in your service discovery) to pick one of the three hosts.

{
    "endpoints": [
        {
            "endpoint": "/v1/products",
            "method": "GET",
            "backend": [
                {
                    "url_pattern": "/products",
                    "host": [
                        "https://products-01.myapi.com:8000",
                        "https://products-02.myapi.com:8000",
                        "https://products-03.myapi.com:8000"
                    ]
                },
                {
                    "url_pattern": "/offers",
                    "host": [
                        "https://marketing.myapi.com:8000"
                    ]
                }
            ]
        }
    ]
}

Disable RESTful checking

By default KrakenD only works with RESTful URL patterns to connect to backends. Enable the option disable_rest in the root of your configuration if you have backends that aren’t RESTful, e.g.: /url.{some_variable}.json

{
  "$schema": "https://www.krakend.io/schema/v3.json",
  "version": 3,
  "disable_rest": true,
  "endpoints": [
    {
      "endpoint": "/foo",
      "backend": [
        {
          "host": [
            "http://mybackend"
          ],
          "url_pattern": "/url.{some_variable}.json"
        }
      ]
    }
  ]
}

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.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information