degraphql
The degraphql plugin maps an HTTP route to a predefined GraphQL query. Clients can call the route without constructing a GraphQL document, while the plugin sends the configured query and selected request values to the upstream GraphQL service.
For POST requests, configured variables come from a JSON request body. For GET requests, they come from URL query parameters.
Examples
The examples use the maintained Pokémon GraphQL API at https://graphqlpokemon.favware.tech/v8. The first example sends a fixed query, and the second updates the same route to accept a variable.
Send a Fixed Query
The route sends this query whenever it receives a POST request:
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
Create the route:
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/degraphql-pokemon" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/v8",
"methods": ["POST"],
"plugins": {
"degraphql": {
"query": "{\n getPokemon(pokemon: pikachu) {\n key\n color\n species\n }\n}"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"graphqlpokemon.favware.tech:443": 1
},
"scheme": "https",
"pass_host": "node"
}
}'
services:
- name: degraphql-pokemon
labels:
docs-example: degraphql
routes:
- name: degraphql-pokemon
uris:
- /v8
methods:
- POST
plugins:
degraphql:
query: |
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
upstream:
type: roundrobin
nodes:
- host: graphqlpokemon.favware.tech
port: 443
weight: 1
scheme: https
pass_host: node
Preview changes owned by this example and confirm that the diff contains no unintended updates or deletions:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
Synchronize the reviewed service configuration:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
- Gateway API
- APISIX CRD
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: graphql-pokemon
spec:
type: ExternalName
externalName: graphqlpokemon.favware.tech
ports:
- name: https
port: 443
targetPort: 443
---
apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: aic
name: graphql-pokemon-https
spec:
targetRefs:
- name: graphql-pokemon
kind: Service
group: ""
sectionName: https
passHost: node
scheme: https
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: degraphql-pokemon
spec:
plugins:
- name: degraphql
config:
query: |
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /v8
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: degraphql-pokemon
backendRefs:
- name: graphql-pokemon
port: 443
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: graphql-pokemon
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: graphqlpokemon.favware.tech
port: 443
scheme: https
passHost: node
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
ingressClassName: apisix
http:
- name: degraphql-pokemon
match:
paths:
- /v8
methods:
- POST
upstreams:
- name: graphql-pokemon
plugins:
- name: degraphql
enable: true
config:
query: |
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
Apply the configuration:
kubectl apply -f degraphql-ic.yaml
Send a POST request without a GraphQL body:
curl "http://127.0.0.1:9080/v8" -X POST
The response should contain the selected Pokémon fields:
{
"data": {
"getPokemon": {
"key": "pikachu",
"color": "Yellow",
"species": "pikachu"
}
}
}
Pass a Variable
The following example demonstrates how to pass a request value to the GraphQL operation through a variable named pokemon.
Update the route to use the variable:
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/degraphql-pokemon" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/v8",
"methods": ["GET", "POST"],
"plugins": {
"degraphql": {
"query": "query ($pokemon: PokemonEnum!) {\n getPokemon(pokemon: $pokemon) {\n key\n color\n species\n }\n}",
"variables": ["pokemon"]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"graphqlpokemon.favware.tech:443": 1
},
"scheme": "https",
"pass_host": "node"
}
}'
services:
- name: degraphql-pokemon
labels:
docs-example: degraphql
routes:
- name: degraphql-pokemon
uris:
- /v8
methods:
- GET
- POST
plugins:
degraphql:
query: |
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
variables:
- pokemon
upstream:
type: roundrobin
nodes:
- host: graphqlpokemon.favware.tech
port: 443
weight: 1
scheme: https
pass_host: node
Preview the update:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
Synchronize the reviewed service configuration:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
- Gateway API
- APISIX CRD
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: graphql-pokemon
spec:
type: ExternalName
externalName: graphqlpokemon.favware.tech
ports:
- name: https
port: 443
targetPort: 443
---
apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: aic
name: graphql-pokemon-https
spec:
targetRefs:
- name: graphql-pokemon
kind: Service
group: ""
sectionName: https
passHost: node
scheme: https
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: degraphql-pokemon
spec:
plugins:
- name: degraphql
config:
query: |
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
variables:
- pokemon
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /v8
method: GET
- path:
type: Exact
value: /v8
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: degraphql-pokemon
backendRefs:
- name: graphql-pokemon
port: 443
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: graphql-pokemon
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: graphqlpokemon.favware.tech
port: 443
scheme: https
passHost: node
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
ingressClassName: apisix
http:
- name: degraphql-pokemon
match:
paths:
- /v8
methods:
- GET
- POST
upstreams:
- name: graphql-pokemon
plugins:
- name: degraphql
enable: true
config:
query: |
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
variables:
- pokemon
Apply the updated configuration:
kubectl apply -f degraphql-ic.yaml
For a POST request, provide the configured variable in a JSON body:
curl "http://127.0.0.1:9080/v8" -X POST \
-H "Content-Type: application/json" \
-d '{
"pokemon": "pikachu"
}'
The response should contain the requested Pokémon:
{
"data": {
"getPokemon": {
"key": "pikachu",
"color": "Yellow",
"species": "pikachu"
}
}
}
For a GET request, provide the variable as a URL query parameter:
curl "http://127.0.0.1:9080/v8?pokemon=pikachu" \
-H "x-apollo-operation-name: GET"
The Pokémon API uses Apollo Server CSRF prevention and requires the x-apollo-operation-name header for GET requests. This requirement comes from the upstream API, not from degraphql. The response should match the POST result.