Map URIs into GraphQL queries with DeGraphQL

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

Kong Konnect

This is a Konnect tutorial. If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
- Control Plane Name: You can use an existing Control Plane or create a new one to use for this tutorial.
- Konnect Proxy URL: By default, a self-hosted Data Plane uses http://localhost:8000. You can set up Data Plane nodes for your Control Plane from the Gateway Manager in Konnect.

Set the personal access token, the Control Plane name, the Control Plane URL, and the Konnect proxy URL as environment variables:

 export DECK_KONNECT_TOKEN='YOUR KONNECT TOKEN'
 export DECK_KONNECT_CONTROL_PLANE_NAME='YOUR CONTROL PLANE NAME'
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='KONNECT PROXY URL'

Kong Gateway running

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

Run the quickstart script:

 curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA 

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

decK

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

GitHub account and access token

For this task, you need a GitHub account and a personal access token to access the GitHub API.

For the purposes of the example, the token must contain read permissions for your user profile.

Export the token into an environment variable:

export GITHUB_TOKEN='YOUR TOKEN GOES HERE'

Create a Gateway Service and a Route

DeGraphQL needs a GraphQL endpoint to query. In this tutorial, we’re going to build a REST API around the https://api.github.com GraphQL service. Make sure you have created a GitHub personal access token to use with the API.

Create a Gateway Service and Route in Kong Gateway, with the Service pointing to the https://api.github.com API:

echo '
_format_version: "3.0"
services:
  - name: github
    tags:
    - graphql
    url: https://api.github.com
    routes:
    - name: github-api
      paths:
      - "/api"
' | deck gateway apply -

Configure the DeGraphQL plugin on the Service

Set up the DeGraphQL plugin on the github Service:

echo '
_format_version: "3.0"
plugins:
  - name: degraphql
    service: github
' | deck gateway apply -

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

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

Let’s add a DeGraphQL route to retrieve the username of the logged in user:

echo '
_format_version: "3.0"
_info:
  default_lookup_tags:
    services:
      - graphql
custom_entities:
  - type: degraphql_routes
    fields:
      service:
        name: "github"
      uri: /me
      query: "query { viewer { login } }"
' | deck gateway apply -

You don’t need to include the GraphQL server path prefix in the URI parameter (/graphql by default), so the URI is just /me.

Validate

Now you can send HTTP requests to the GraphQL endpoint without having to pass GraphQL queries directly.

Send a GET request to the /me endpoint to retrieve your username:

curl "$KONNECT_PROXY_URL/api/me" \
     -H "Authorization: Bearer $GITHUB_TOKEN"

curl "http://localhost:8000/api/me" \
     -H "Authorization: Bearer $GITHUB_TOKEN"

You’ll get your GitHub username in response:

{"data":{"viewer":{"login":"your-username"}}}

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d