a6-recipe-graphql-proxy

Overview

APISIX provides built-in GraphQL support through three variables that let you route and apply policies based on GraphQL query content — without parsing GraphQL yourself:

Variable	Description	Example Value
`graphql_name`	Operation name from the query	`"getUser"`
`graphql_operation`	Operation type	`"query"`, `"mutation"`
`graphql_root_fields`	Top-level fields requested	`["user", "orders"]`

These variables are extracted automatically from POST requests with Content-Type: application/json or application/graphql, and from GET requests with a query parameter.

When to Use

Routing different GraphQL operations to different backends
Applying rate limits per operation type (queries vs mutations)
Restricting which operations specific consumers can execute
Converting REST endpoints to GraphQL queries (degraphql)
Adding security layers (auth, rate limiting) to a GraphQL API

Approach A: Operation-Based Routing

Route GraphQL queries and mutations to different backends using the graphql_operation variable.

Route queries to read replicas, mutations to primary

# Queries → read replica
a6 route create -f - <<'EOF'
{
  "id": "graphql-queries",
  "uri": "/graphql",
  "vars": [["graphql_operation", "==", "query"]],
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-read-replica:4000": 1 }
  }
}
EOF

# Mutations → primary database
a6 route create -f - <<'EOF'
{
  "id": "graphql-mutations",
  "uri": "/graphql",
  "vars": [["graphql_operation", "==", "mutation"]],
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-primary:4000": 1 }
  }
}
EOF

Route by operation name

# Route the expensive "analytics" query to a dedicated backend
a6 route create -f - <<'EOF'
{
  "id": "graphql-analytics",
  "uri": "/graphql",
  "vars": [["graphql_name", "==", "getAnalytics"]],
  "priority": 10,
  "upstream": {
    "type": "roundrobin",
    "nodes": { "analytics-backend:4000": 1 }
  }
}
EOF

The priority field ensures this route is matched before a generic /graphql route.

Approach B: Per-Operation Rate Limiting

Apply different rate limits to queries vs mutations.

# Queries: 1000 req/min
a6 route create -f - <<'EOF'
{
  "id": "graphql-query-limited",
  "uri": "/graphql",
  "vars": [["graphql_operation", "==", "query"]],
  "plugins": {
    "key-auth": {},
    "limit-count": {
      "count": 1000,
      "time_window": 60,
      "key_type": "var",
      "key": "consumer_name",
      "rejected_code": 429
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-backend:4000": 1 }
  }
}
EOF

# Mutations: 100 req/min (more restrictive)
a6 route create -f - <<'EOF'
{
  "id": "graphql-mutation-limited",
  "uri": "/graphql",
  "vars": [["graphql_operation", "==", "mutation"]],
  "plugins": {
    "key-auth": {},
    "limit-count": {
      "count": 100,
      "time_window": 60,
      "key_type": "var",
      "key": "consumer_name",
      "rejected_code": 429,
      "rejected_msg": "Mutation rate limit exceeded"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-backend:4000": 1 }
  }
}
EOF

Approach C: Restrict Operations by Consumer

Use consumer-restriction to allow only specific consumers to execute mutations.

a6 route create -f - <<'EOF'
{
  "id": "graphql-mutations-restricted",
  "uri": "/graphql",
  "vars": [["graphql_operation", "==", "mutation"]],
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["admin-user", "service-account"],
      "rejected_code": 403,
      "rejected_msg": "Mutations not allowed for your account"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-backend:4000": 1 }
  }
}
EOF

Approach D: REST-to-GraphQL with degraphql

The degraphql plugin converts RESTful endpoints into GraphQL queries, allowing REST clients to consume a GraphQL backend.

1. Enable degraphql on a route

a6 route create -f - <<'EOF'
{
  "id": "rest-to-graphql-users",
  "uri": "/users/:id",
  "methods": ["GET"],
  "plugins": {
    "degraphql": {
      "query": "query getUser($id: ID!) { user(id: $id) { id name email } }",
      "variables": ["id"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-backend:4000": 1 }
  }
}
EOF

REST clients call GET /users/123 and receive the GraphQL response for user(id: "123").

2. Static query (no variables)

a6 route create -f - <<'EOF'
{
  "id": "rest-to-graphql-stats",
  "uri": "/stats",
  "methods": ["GET"],
  "plugins": {
    "degraphql": {
      "query": "{ systemStats { cpu memory uptime } }"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "graphql-backend:4000": 1 }
  }
}
EOF

Declarative GraphQL Config

# apisix-graphql.yaml
routes:
  - id: graphql-queries
    uri: "/graphql"
    vars: [["graphql_operation", "==", "query"]]
    plugins:
      key-auth: {}
      limit-count:
        count: 1000
        time_window: 60
        key_type: var
        key: consumer_name
    upstream:
      type: roundrobin
      nodes:
        "graphql-read-replica:4000": 1

  - id: graphql-mutations
    uri: "/graphql"
    vars: [["graphql_operation", "==", "mutation"]]
    plugins:
      key-auth: {}
      limit-count:
        count: 100
        time_window: 60
        key_type: var
        key: consumer_name
      consumer-restriction:
        whitelist: ["admin-user", "service-account"]
    upstream:
      type: roundrobin
      nodes:
        "graphql-primary:4000": 1

a6 config diff -f apisix-graphql.yaml
a6 config sync -f apisix-graphql.yaml

Gotchas

Body size limit — APISIX parses GraphQL from the request body. Default max body size is 1 MiB (configurable via client_max_body_size in APISIX config). Large queries may be rejected.
Single operation only — APISIX extracts variables from the first operation in the request. Batched GraphQL queries (multiple operations) are not supported for routing purposes.
No WebSocket subscriptions — GraphQL subscriptions over WebSocket are not supported by the built-in GraphQL parsing. You can still proxy WebSocket connections, but without operation-based routing.
POST content types — GraphQL parsing works with application/json (standard) and application/graphql (query in body as text). Other content types are not parsed.
GET requests — GraphQL variables are read from the query URL parameter (URL-encoded GraphQL query string).
vars matching — the vars field on a route accepts an array of conditions. Each condition is ["variable", "operator", "value"]. Multiple conditions are AND-ed together.
degraphql limitations — the plugin sends a POST with application/json to the upstream, regardless of the original request method. The variables field maps URI path parameters to GraphQL variables by name.
Priority for overlapping routes — when multiple routes match /graphql with different vars, use the priority field to control matching order. Higher priority = matched first.

Verification

# Test query routing
curl -X POST http://localhost:9080/graphql \
  -H "Content-Type: application/json" \
  -H "apikey: my-key" \
  -d '{"query": "query getUser { user(id: 1) { name } }"}'

# Test mutation routing
curl -X POST http://localhost:9080/graphql \
  -H "Content-Type: application/json" \
  -H "apikey: my-key" \
  -d '{"query": "mutation createUser { createUser(name: \"test\") { id } }"}'

# Test rate limiting (should 429 after exceeding limit)
for i in $(seq 1 1001); do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -X POST http://localhost:9080/graphql \
    -H "Content-Type: application/json" \
    -H "apikey: my-key" \
    -d '{"query": "{ users { id } }"}'
done

# Test REST-to-GraphQL
curl http://localhost:9080/users/123
# Returns GraphQL response for user(id: "123")