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:

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"
    }
  }'

adc.yaml

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

degraphql-ic.yaml

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

degraphql-ic.yaml

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

Update the route to use a GraphQL variable named pokemon:

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

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"
    }
  }'

adc.yaml

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

degraphql-ic.yaml

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

degraphql-ic.yaml

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.