GraphQL on Zuplo — Example

A complete, runnable Zuplo gateway that proxies a public GraphQL API and layers on the features GraphQL clients usually have to build themselves: edge caching, query depth limiting, and operation analytics.

It proxies the public Countries GraphQL API, so it works the moment it's deployed — no API keys or upstream setup required.

Deploy in one click

Click the button below and Zuplo will create a copy of this project in your account, then build and deploy it for you.

The button opens the Zuplo portal, where you pick an account and project name. Prefer the URL? https://portal.zuplo.com/zup-it?sourceRepoUrl=https://github.com/zuplo-samples/graphql

What's inside

├─ config/
│  ├─ routes.oas.json   # POST /graphql route (URL Rewrite handler, tagged x-graphql)
│  └─ policies.json     # GraphQL cache, depth limit, and analytics policies
├─ docs/                # Developer portal (Zudoku) with a GraphQL playground
│  ├─ pages/
│  ├─ zudoku.config.ts
│  ├─ package.json
│  └─ tsconfig.json
├─ zuplo.jsonc          # Project configuration
└─ package.json

The gateway

A single POST /graphql route forwards operations to the upstream API and runs three GraphQL-aware policies:

Policy	What it does
graphql-cache-inbound	Caches identical query operations at the edge (x-cache: HIT on reuse)
graphql-complexity-limit-inbound	Rejects queries nested deeper than 15 levels before they hit the origin
graphql-analytics-outbound	Classifies and reports failed operations to GraphQL analytics

The route is tagged with the x-graphql extension, which lights up the GraphQL analytics view and the GraphQL badge in the Route Designer.

The developer portal

The docs/ folder is a Zudoku developer portal wired with @zudoku/plugin-graphql. It renders a browsable, typed schema reference and an interactive playground from the GraphQL schema.

Query it

Once deployed, send a query to your /graphql route:

curl --request POST \
  --url https://<your-project>.zuplo.app/graphql \
  --header 'content-type: application/json' \
  --data '{"query":"{ countries { code name emoji } }"}'

Send the same query twice and inspect the response headers — the second response returns x-cache: HIT, served from the edge cache.

Run locally

npm install
npm run dev        # start the gateway on http://localhost:9000
npm run docs       # start the developer portal

Point it at your own API

Swap the upstream in config/routes.oas.json for your own GraphQL endpoint:

"options": {
  "rewritePattern": "https://api.example.com/graphql"
}

To use a different backend per environment, reference an environment variable such as ${env.GRAPHQL_API_URL} instead of a hard-coded URL.

Learn more

• GraphQL on Zuplo — set up the endpoint and Dev Portal docs
• Secure your GraphQL API — complexity limits and introspection controls
• Cache GraphQL responses — serve repeated queries from the edge