degraphql

Description

The degraphql Plugin supports communicating with upstream GraphQL services over regular HTTP requests by mapping GraphQL queries to HTTP endpoints.

Attributes

Name	Type	Required	Description
query	string	True	The GraphQL query sent to the Upstream.
operation_name	string	False	The name of the operation, only required if multiple operations are present in the query.
variables	array[string]	False	The names of variables used in the GraphQL query, extracted from the request body or query string.

Examples

The examples below demonstrate how you can configure degraphql for different scenarios.

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

The examples below use Pokemon GraphQL API as the upstream GraphQL server.

Transform a Basic Query

The following example demonstrates how to transform a simple GraphQL query:

query {
  getAllPokemon {
    key
    color
  }
}

Create a Route with the degraphql Plugin as follows:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "degraphql-route",
    "methods": ["POST"],
    "uri": "/v8",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "graphqlpokemon.favware.tech": 1
      },
      "scheme": "https",
      "pass_host": "node"
    },
    "plugins": {
      "degraphql": {
        "query": "{\n  getAllPokemon {\n    key\n    color\n  }\n}"
      }
    }
  }'

Send a request to the Route to verify:

curl "http://127.0.0.1:9080/v8" -X POST

You should see a response similar to the following:

{
  "data": {
    "getAllPokemon": [
      { "key": "pokestarsmeargle", "color": "White" },
      { "key": "pokestarufo", "color": "White" },
      { "key": "pokestarufo2", "color": "White" },
      ...
      { "key": "terapagosstellar", "color": "Blue" },
      { "key": "pecharunt", "color": "Purple" }
    ]
  }
}

Transform a Query with Variables

The following example demonstrates how to transform a GraphQL query that uses a variable:

query ($pokemon: PokemonEnum!) {
  getPokemon(
    pokemon: $pokemon
  ) {
    color
    species
  }
}

variables:
{
  "pokemon": "pikachu"
}

Create a Route with the degraphql Plugin as follows:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "degraphql-route",
    "uri": "/v8",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "graphqlpokemon.favware.tech": 1
      },
      "scheme": "https",
      "pass_host": "node"
    },
    "plugins": {
      "degraphql": {
        "query": "query ($pokemon: PokemonEnum!) {\n  getPokemon(\n    pokemon: $pokemon\n  ) {\n    color\n    species\n  }\n}\n",
        "variables": ["pokemon"]
      }
    }
  }'

Send a POST request to the Route with the variable in the request body:

curl "http://127.0.0.1:9080/v8" -X POST \
  -d '{
    "pokemon": "pikachu"
  }'

You should see a response similar to the following:

{
  "data": {
    "getPokemon": {
      "color": "Yellow",
      "species": "pikachu"
    }
  }
}

Alternatively, you can also pass the variable in the URL query string of a GET request:

curl "http://127.0.0.1:9080/v8?pokemon=pikachu"

You should see the same response as the previous.