GraphQL

GraphQL on Zuplo

Zuplo has rich support for GraphQL. Pass your requests through the gateway, attach policies, track operations with analytics, and publish documentation for your schema in the Dev Portal. This guide walks you through setting it up.

TL;DR

Proxy your GraphQL endpoint through a POST /graphql route with the URL Rewrite handler
Tag the route with the x-graphql extension
Surface failed operations with the graphql-analytics-outbound policy
Add caching and security policies to protect and accelerate the endpoint
Add the graphqlPlugin to the Developer Portal

Add a GraphQL endpoint to your gateway

Set up the route with a URL Rewrite handler and set the rewrite URL to your upstream GraphQL server (for example, https://api.example.com/graphql).

Add a new GraphQL route

Open the Route Designer

In the Zuplo Portal, open the Code tab and click routes.oas.json. This opens the Route Designer, which lists your project's existing routes and an Add menu.
Add the endpoint

Click Add and select GraphQL Endpoint. This creates a POST /graphql route preconfigured with the URL Rewrite handler, a demo upstream, and the GraphQL Analytics policy for error reporting. GraphQL routes show a GraphQL badge in the route list.
Point it at your upstream

Expand the new route. Its handler is preset to URL Rewrite in the Request Handler drop-down; in the URL text box below it, replace the demo URL with your GraphQL API's endpoint, for example https://api.example.com/graphql. To use a different backend per environment, reference an environment variable such as ${env.GRAPHQL_API_URL}.
Save

Save your changes. Your gateway now proxies GraphQL requests at /graphql.

Mark an existing route as GraphQL

Already proxying a GraphQL API through a regular route? Open the route in the Route Designer, click the ⋯ menu at the end of the route's options row (next to the CORS and docs toggles), and check Mark as GraphQL. This tags the route as a GraphQL endpoint without changing its handler or policies.

The resulting route configuration

Both paths produce a route in routes.oas.json with the x-graphql extension set:


config/routes.oas.json
{
  "paths": {
    "/graphql": {
      "post": {
        "summary": "GraphQL Endpoint",
        "x-graphql": true,
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "export": "urlRewriteHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "rewritePattern": "https://api.example.com/graphql"
            }
          },
          "policies": {
            "inbound": []
          }
        },
        "operationId": "graphql-1a2bc3d4"
      }
    }
  }
}

Secure the endpoint

Zuplo ships policies for query depth, complexity, and introspection. See Secure your GraphQL API to add complexity limits and disable introspection in production.

To fine-tune analytics, see the GraphQL Analytics policy reference for the full set of options.

Protect and accelerate the endpoint

Once requests are flowing, attach GraphQL-aware policies to the route. Zuplo ships a set built specifically for the GraphQL request shape:

Goal	Policy
Cache repeated queries at the edge	`graphql-cache-inbound`
Block deep or expensive queries	`graphql-complexity-limit-inbound`
Disable schema introspection in production	`graphql-disable-introspection-inbound`
Hide sensitive types from introspection	`graphql-introspection-filter-outbound`
Report failed operations to analytics	`graphql-analytics-outbound`

See Secure your GraphQL API for the complexity and introspection policies, and Cache GraphQL responses to serve identical queries from the edge.

Document the API in your Dev Portal

The @zudoku/plugin-graphql package renders a browsable type reference and a playground in your Dev Portal, generated from your schema. Register one instance per API.

Import graphqlPlugin and add an instance per API. The path is where the docs mount, and schema points at your GraphQL API — either a live endpoint URL or a path to a schema definition language (SDL) file. Define the path once as a const and reference the same value from both the plugin and the navigation link, so the link can never point at a path the plugin isn't mounted at:


zudoku.config.tsx
import { graphqlPlugin } from "@zudoku/plugin-graphql";

const graphqlPath = "/graphql";

const config = {
  navigation: [
    {
      type: "link",
      label: "GraphQL API",
      to: graphqlPath,
    },
  ],
  plugins: [
    graphqlPlugin({
      schema: "./schema.graphql", // Also accepts a URL, e.g. https://...
      path: graphqlPath,
      // endpoint: "/my-graphql", // Optional, defaults to "/graphql"
    }),
  ],
};

export default config;

You can register the plugin more than once to document several schemas, each with its own path.

Verify it worked

Open your Dev Portal, navigate to the GraphQL API, and run a query in the playground. A successful response confirms the gateway is proxying requests and the playground is pointed at the right endpoint.

Next steps

Secure your GraphQL API — complexity limits and introspection policies
Cache GraphQL responses — serve repeated queries from the edge
Testing GraphQL queries — test the endpoint from the Zuplo Portal or external tools
GraphQL analytics — monitor operation volume, latency, and error classes once traffic flows
URL Rewrite handler — full reference for the handler GraphQL routes use
MCP Server GraphQL endpoints — expose GraphQL queries as MCP tools for AI agents

Edit this page

Last modified on June 29, 2026

Overview Secure your GraphQL API