Document updated on Nov 3, 2021

GraphQL gateway

The GraphQL integration allows you to work in two different modes:

1. Apply gateway functionality in the middle of a GraphQL client and its GraphQL servers (just proxy)
2. Convert REST endpoints to GraphQL calls (adapter/transformer).

KrakenD offers a simple yet powerful way of consuming GraphQL content from your distributed graphs. The main benefits of using KrakenD as a GraphQL Gateway are:

• Simple GraphQL Federation: chop your monolithic GraphQL server into different services and aggregate them in the gateway.
• User validation: Handle the authorization in the gateway before adding any load to your GraphQL servers.
• Protect and secure internal GraphQL endpoints
• Rate limit GraphQL usage
• Prepare aggregated data for external caching
• Hide complexity to the clients by providing a REST interface

REST to GraphQL transformation

In this scenario, the end-user consumes traditional REST content, without even knowing that there is a GraphQL server behind:

KrakenD can use the variables in the body or in the endpoint URL to generate the final GraphQL query that will be sent to the GraphQL server. The query is loaded from an external file or declared inline in the configuration and contains any variables needing replacement with the user input.

KrakenD acts as the GraphQL client, negotiating with the GraphQL server the content and hiding its complexity to the end-user. The end-user consumes REST content and retrieves the data in JSON, XML, RSS, or any other format supported by KrakenD.

The configuration to consume GraphQL content from your GrapQL graphs could look like this:

{
    "endpoint": "/marketing/{user_id}",
	"method": "POST",
    "backend": [
        {
            "timeout": "4100ms",
            "url_pattern": "/graphql?timeout=4s",
            "extra_config": {
                "backend/graphql": {
                    "type":  "mutation",
                    "query_path": "./graphql/mutations/marketing.graphql",
                    "variables": {
                        "user":"{user_id}",
                        "other_static_variables": {
                            "foo": false,
                            "bar": true
                        }
                    },
                    "operationName": "addMktPreferencesForUser"
                }
            }
        }
    ]
}

In the example above, the GraphQL server receives a variable user with the {user_id} declared in the endpoint. The dictionary can have any nesting level you need, but nested variables cannot contain {placeholders}.

The configuration for the namespace backend/graphql has the following structure:

When using an inline query (as opposed to using a file from the query_path), make sure to use escaping when needed. Examples: - "query": "{ \n find_follower(func: uid(\"0x3\")) {\n name \n }\n }". - "query": "{ q(func: uid(1)) { uid } }"

The combination of type and the endpoint/backend method has the following behavior:

• GET: The query to the GQL server uses an autogenerated query string with all the variables.
• POST: The query to the GQL server contains all variables in the body of the request. When the user and the KrakenD configuration define the same variables (collision) the user variables take preference.

That being said:

• method=get + type=query: Generates a querystring using any {variables} in the endpoint
• method=post + type=query: Generates a body using any {variables} in the endpoint
• method=get + type=mutation: Generates a querystring including any variables in the body of the REST call
• method=post + type=mutation: Generates a body including any variables in the REST body plus the ones in the configuration

GraphQL gateway as a proxy

In this approach, KrakenD gets in the middle to validate or rate limit requests, but the request is forwarded to the GraphQL servers, who receive the original GraphQL query from the end-user.

When working in this mode, all you need to do is to configure the GraphQL endpoint, and add as the backend your GraphQL. An example:

{
    "endpoint": "/graphql",
	"input_query_strings":[
		"query",
		"operationName",
		"variables"
	],
	"backend": [
        {
            "timeout": "4100ms",
            "host": ["http://your-graphql.server:4000"],
            "url_pattern": "/graphql?timeout=4s"
        }
    ]
}

The previous example uses a set of recognized query strings to pass to the GraphQL server. You can also use "input_query_strings":["*"] to forward any query string. The exact configuration works with a POST method.

As the configuration above is not using no-op, you can take the oprotunity to connect to more servers in the same endpoint by adding additional backend objects in the configuration.

GraphQL Federation

KrakenD’s principles are working with simultaneous aggregation of data. In that sense, consuming multiple subgraphs (or back-end services) comes naturally. However, using the REST to GraphQL capabilities, you can federate data using a simple strategy: define the subgraphs in the configuration instead of moving this responsibility to the consumer.

It is a simplistic approach but still very powerful, as you can define templates with queries and let krakend do the aggregation of the responses.

Create rest endpoints with fixed graphs you’d like to consume in the configuration. Then, in each back-end query (subgraph), you decide what transformation rules to apply, the validation, rate-limiting, etc., and even connect your endpoints with other services like queues.

The following example is a REST endpoint consuming data from 2 different subgraphs in parallel. You could add here any other KrakenD components you could need:

{
    "endpoint": "/user-data/{id_user}",
    "backend": [
        {
            "timeout": "3100ms",
            "url_pattern": "/graphql?timeout=3s",
            "group": "user",
			"method": "GET",
            "host": ["http://user-graph:4000"],
            "extra_config": {
                "backend/graphql": {
                    "type":  "query",
                    "query_path": "./graphql/queries/user.graphql",
                    "variables": {
                        "user":"{user_id}"
                    },
                    "operationName": "getUserData"
                }
            }
        },
        {
            "timeout": "2100ms",
            "url_pattern": "/graphql?timeout=2s",
            "group": "user_metadata",
			"method": "GET",
            "host": ["http://metadata:4000"],
            "extra_config": {
                "backend/graphql": {
                    "type":  "query",
                    "query_path": "./graphql/queries/user_metadata.graphql",
                    "variables": {
                        "user":"{user_id}"
                    },
                    "operationName": "getUserMetadata"
                }
            }
        }
    ]
}