Document updated on Oct 21, 2022
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. If a backend has more than one host, then the array is the egress load balancing list.
When a KrakenD endpoint is hit, the engine requests all defined backends in parallel (unless a sequential proxy is used) and the content merged and aggregated (unless you just proxy using the no-op encoding). The returned content is parsed according to its encoding or in some cases its extra_config configuration.
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"
}
The url_pattern accepts {variables} from the endpoint definition, and on Enterprise
you can also inject headers with patterns like /{input_headers.X-Tenant}/foo
All the options relative to the backend definition are:
Fields of Backend Object
allowarray- 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.bremoves{"a":{"b": true}}Examples:"token","CVV","password" denyarray- 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.bremoves{"a":{"b": true}}. disable_host_sanitizeboolean- Set it to
truewhen the host doesn’t need to be checked for an HTTP protocol. This is the case ofsd=dnsor when using other protocols likeamqp://,nats://,kafka://, etc. When set to true, and the protocol is not HTTP, KrakenD fails with aninvalid hosterror.Defaults tofalse encoding- Defines your needed encoding to set how to parse the response. Defaults to the value of its endpoint’s
encoding, or tojsonif not defined anywhere else.Possible values are:"json","safejson","fast-json","xml","rss","string","no-op"Defaults to"json" extra_configobject- 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.
groupstring- 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" hostarray- 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 thehostdeclaration at the configuration’s root level, and the service fails starting when there is none. is_collectionboolean- Set to true when your API does not return an object {} but a collection []Defaults to
true mappingobject- 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.Example:
{"from":"to"} method- 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- The Service Discovery system to resolve your backend services. Defaults to
static(no external Service Discovery). Usednsto use DNS SRV records.Possible values are:"static","dns"Defaults to"static" targetstring- Removes the matching object from the reponse and returns only its contents.Examples:
"data","content","response" url_pattern* string- The path inside the service (no protocol, no host, no method). E.g:
/users. Some functionalities underextra_configmight drop the requirement of declaring a validurl_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.Examples:"/users","/user/{id_user}"
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/v2.3/krakend.json",
"version": 3,
"disable_rest": true,
"endpoints": [
{
"endpoint": "/foo",
"backend": [
{
"host": [
"http://mybackend"
],
"url_pattern": "/url.{some_variable}.json"
}
]
}
]
}Connecting to HTTPS backends with self-signed certificates
When using self-signed certificates in your backends, you must add the certificates to the local CA, or at least add them while developing the allow_insecure_connections setting to true. Example:
{
"version": 3,
"allow_insecure_connections": true,
"endpoints": []
}
