DeGraphQL

This plugin transforms a GraphQL upstream into a traditional endpoint by mapping URIs into GraphQL queries.

Configuration Reference

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

• Setting a target's health status in the load balancer
• Validating configurations against schemas
• Uploading the declarative configuration using the /config endpoint

Example plugin configuration

curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
    --data "name=degraphql" 

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: degraphql-example
config:
  EXAMPLE_PARAMETER: EXAMPLE_VALUE
plugin: degraphql

apiVersion: v1
kind: Service
metadata:
  name: SERVICE_NAME|SERVICE_ID
  labels:
    app: SERVICE_NAME|SERVICE_ID
  annotations:
    konghq.com/plugins: degraphql-example
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: SERVICE_NAME|SERVICE_ID
  selector:
    app: SERVICE_NAME|SERVICE_ID

plugins:
- name: degraphql
  service: SERVICE_NAME|SERVICE_ID
  config:
    EXAMPLE_PARAMETER: EXAMPLE_VALUE

curl -X POST http://localhost:8001/plugins/ \
  --data "name=degraphql" 

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-degraphql>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config:
  <optional_parameter>: <value>
plugin: degraphql

plugins:
- name: degraphql
  config:
    EXAMPLE_PARAMETER: EXAMPLE_VALUE

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Usage

DeGraphQL needs a GraphQL endpoint to query. As an example, we are going to build a REST API around the https://api.github.com GraphQL service. For that reason, the following examples include the header Authorization: Bearer some-token.

This plugin must be activated on a service that points to a GraphQL endpoint.

Create a Service and a Route

Create a Service and Route in Kong Gateway:

curl -X POST http://localhost:8001/services \
  --data name="github" \
  --data url="https://api.github.com"

curl -X POST http://localhost:8001/services/github/routes \
  --data paths="/api"

Configure the plugin on the Service

Set up the DeGraphQL plugin:

curl -X POST http://localhost:8001/services/github/plugins \
  --data name="degraphql"

Enabling the plugin disables regular service function. Instead, the plugin now builds the path and GraphQL query to hit the GraphQL service with.

From this point on, the Service represents your REST API and not the GraphQL endpoint itself. It will return a 404 Not Found status code if no DeGraphQL routes have been configured.

Configure DeGraphQL Routes on the Service

Once the plugin is activated on a Service, you can add your own routes by defining URIs and associating them to GraphQL queries.

Don’t include the GraphQL server path prefix in the URI parameter (/graphql by default).

curl -X POST http://localhost:8001/services/github/degraphql/routes \
  --data uri="/me" \
  --data query="query { viewer { login } }"

curl http://localhost:8000/api/me \
  --header "Authorization: Bearer some-token"
{
    "data": {
        "viewer": {
            "login": "you"
        }
    }
}

GraphQL query variables can be defined on URIs:

curl -X POST http://localhost:8001/services/github/degraphql/routes \
  --data uri='/:owner/:name' \
  --data query='query ($owner:String! $name:String!){
                  repository(owner:$owner, name:$name) {
                    name
                    forkCount
                    description
                 }
               }'

curl http://localhost:8000/api/kong/kong \
  --header "Authorization: Bearer some-token"
{
  "data": {
      "repository": {
          "description": "🦍 The Cloud-Native API Gateway ",
          "forkCount": 2997,
          "name": "kong"
      }
  }
}

The same variables can also be provided as GET arguments:

curl -X POST http://localhost:8001/services/github/degraphql/routes \
  --data uri='/repo' \
  --data query='query ($owner:String! $name:String!){
                  repository(owner:$owner, name:$name) {
                    name
                    forkCount
                    description
                  }
                }'

curl "http://localhost:8000/api/repo?owner=kong&name=kuma" \
  --header "Authorization: Bearer some-token"
{
  "data": {
      "repository": {
          "description": "🐻 The Universal Service Mesh",
          "forkCount": 48,
          "name": "kuma"
      }
  }
}

Available endpoints

List defined DeGraphQL Routes for a service

Create a DeGraphQL Route for a Service

Edit a DeGraphQL Route for a Service

Delete a DeGraphQL Route for a Service

Changelog

Kong Gateway 3.0.x

• Added the graphql_server_path configuration parameter.