DeGraphQL

You are browsing unreleased documentation.

Looking for the plugin's configuration parameters? You can find them in the DeGraphQL configuration reference doc.

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

 
flowchart LR
A(Devices/apps)
B(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]

style C stroke:#E10098
style Note fill:#fdf3d8,stroke:#e1bb86
style id1 stroke-dasharray:3

end
  

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

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