DeGraphQL

The DeGraphQL plugin transforms GraphQL upstreams into traditional endpoints by mapping URIs into GraphQL queries.

DeGraphQL needs a GraphQL endpoint to query. This plugin must be activated on a Gateway Service or related Route that points to a GraphQL endpoint.

Kong Gateway receives traffic from clients and uses a Gateway Service with DeGraphQL routes to map URIs to GraphQL queries.

 
flowchart LR
A(Devices/apps)
B(Gateway Service with 
DeGraphQL routes)
C( GraphQL)

A<-->B
subgraph id1 [Data center]
subgraph id2 [Kong Gateway]
B
end
B--Query 1-->C
B--Query 2-->C
B--Query 3-->C
B--Query 4-->C

Note[Queries are passed as 
parameters to GraphQL]



end
  

Figure 1: Diagram showing how Kong Gateway receives traffic from clients and uses a Gateway Service with DeGraphQL routes to map URIs to GraphQL queries.

For a complete tutorial, see Map URIs into GraphQL queries with DeGraphQL.

The following sections define some common patterns for DeGraphQL routes.

Don’t include the GraphQL server path prefix in the uri configuration parameter (/graphql by default). Only include the custom portion of the path that you want to configure. For example: uri: /my-path, but not uri: /graphql/my-path.

GraphQL query variables on URIs

GraphQL query variables can be applied on URIs.

Here’s an example query that retrieves GitHub repository info from the GitHub GraphQL API:

_format_version: "3.0"
custom_entities:
  - type: degraphql_routes
    fields:
      service:
        name: "github"
      uri: /me
      query: |-
        query ($owner:String! $name:String!){
                        repository(owner:$owner, name:$name) {
                          name
                          forkCount
                          description
                        }
                      }

You can access the new route via org-name/repo-name:

curl http://localhost:8000/api/kong/kong \
  --header "Authorization: Bearer $GITHUB_TOKEN"

GraphQL query variables as GET arguments

GraphQL query variables can be provided as GET arguments.

Here’s an example query that retrieves GitHub repository info from the GitHub GraphQL API:

_format_version: "3.0"
custom_entities:
  - type: degraphql_routes
    fields:
      service:
        name: "github"
      uri: /me
      query: |-
        query ($owner:String! $name:String!){
                  repository(owner:$owner, name:$name) {
                    name
                    forkCount
                    description
                  }
                }

You can access the new route by appending repo?owner=OWNER_NAME&name=REPO_NAME to the request URL:

curl "http://localhost:8000/api/repo?owner=kong&name=kuma" \
  --header "Authorization: Bearer $GITHUB_TOKEN"