Wrap a GraphQL API Into REST Endpoints: OpenAPI 3.1 Adapters That Don't Leak Schema (2026)

Why a GraphQL Schema Breaks Things Outside Your Frontend

A GraphQL API works well when the client is a React app that already speaks GraphQL. It gets awkward the moment the consumer isn't that app.

A Stripe webhook handler that needs to confirm a subscription tier can't send a query document. A partner integrating through Zapier expects GET /orders/42, not a POST body with a query string embedded in JSON. And an AI agent calling your API through a tool definition works far more reliably against a fixed /users/{id} route than against a schema with 40 optional arguments on a single field.

None of this means GraphQL was the wrong choice for your product's own frontend. It means the frontend's query flexibility isn't a feature for these other callers, it's friction.

The usual first attempt is a single catch-all endpoint that forwards the raw query to the GraphQL server. That's not a wrapper. It's a proxy, and it still requires the caller to know your schema, still returns GraphQL's errors array format, and still bypasses HTTP caching because every request is a POST.

What Changes When You Wrap It Properly

The 5-Phase Workflow

The graphql-to-rest-wrapper skill runs this as one pass through a GraphQL schema or introspection JSON:

1. Ingestion, reads your SDL (schema.graphql) or introspection JSON, plus the specific queries and mutations you want exposed. Queries become GET routes; mutations become POST, PATCH, or DELETE depending on intent.
2. OpenAPI 3.1 synthesis, generates a lint-verified spec for the new REST surface, with RFC 7807 problem details baked into every error response.
3. Route handler generation, writes the actual adapter code in Hono, including the GraphQL client call and the response transform.
4. Caching layer, adds an actual server-side cache (in-memory or Redis) keyed on the query and variables, with a TTL and invalidation on writes, so repeat GETs don't round-trip to the GraphQL resolver. A Cache-Control header on top of that defaults to private, since caching one user's response in a shared cache and serving it to another user is a real data leak, not an edge case.
5. Client SDK generation, produces a typed TypeScript fetch client, typed against the same generated GraphQL operation types Phase 3 uses (not hand-written any stubs), so frontend code calling the new REST layer gets real autocomplete instead of guesswork. TypeScript only, this skill doesn't generate a Python client.

Here's what Phase 3 actually outputs for a GetUserProfile query wrapped into GET /users/:id:

// src/routes/users.ts
import { Hono } from "hono";
import { z } from "zod";
import { GraphQLClient, gql } from "graphql-request";
import type { GetUserProfileQuery, GetUserProfileQueryVariables } from "../generated/graphql"; // codegen output, no `any`

const app = new Hono();
const client = new GraphQLClient(process.env.GRAPHQL_BACKEND_URL!);

const GET_USER_QUERY = gql`
  query GetUserProfile($userId: ID!) {
    user(id: $userId) {
      id
      email
      profile {
        fullName
        avatarUrl
      }
      subscriptions(status: ACTIVE) {
        tier
      }
    }
  }
`;

const ParamsSchema = z.object({ id: z.string().uuid() });

// GraphQL error codes aren't standardized across backends, this map is per-project config.
// Anything not listed falls through to 502 (bad gateway), not 500: a failure calling the
// upstream GraphQL API is this adapter's dependency failing, not a bug in the adapter itself.
const GRAPHQL_ERROR_STATUS_MAP: Record<string, number> = {
  UNAUTHENTICATED: 401,
  FORBIDDEN: 403,
  BAD_USER_INPUT: 400,
  NOT_FOUND: 404,
};

// Type guard replacing `err as any`, narrows `unknown` to only the shape this
// handler actually needs before reading anything off it.
function isGraphQLRequestError(
  err: unknown
): err is { response: { errors: Array<{ extensions?: { code?: string } }> } } {
  return (
    typeof err === "object" &&
    err !== null &&
    "response" in err &&
    typeof (err as { response?: unknown }).response === "object"
  );
}

app.get("/users/:id", async (c) => {
  const parsed = ParamsSchema.safeParse({ id: c.req.param("id") });
  if (!parsed.success) {
    return c.json({ title: "Bad Request", status: 400, detail: "id must be a valid UUID" }, 400);
  }
  const userId = parsed.data.id;

  try {
    const data = await client.request<GetUserProfileQuery, GetUserProfileQueryVariables>(GET_USER_QUERY, { userId });
    if (!data.user) {
      return c.json({ title: "Not Found", status: 404, detail: `User ${userId} does not exist` }, 404);
    }
    return c.json({
      id: data.user.id,
      email: data.user.email,
      name: data.user.profile.fullName,
      avatar: data.user.profile.avatarUrl,
      tier: data.user.subscriptions[0]?.tier ?? "free"
    });
  } catch (err) {
    const code = isGraphQLRequestError(err) ? err.response.errors[0]?.extensions?.code : undefined;
    const status = (code && GRAPHQL_ERROR_STATUS_MAP[code]) || 502;
    // err.message and the raw GraphQL error body never reach the client, they can contain
    // query/schema internals. Log the real error server-side; return a generic detail instead.
    console.error("graphql-to-rest upstream error", { userId, code, err });
    return c.json({ title: "Upstream Error", status, detail: "The upstream service could not fulfill this request." }, status);
  }
});

export default app;

Notice what's missing from the response: no profile object, no subscriptions array, no trace of the query document, and no raw error message either, however the upstream call fails. A webhook consuming GET /users/42 sees name and tier, or a generic error detail. It has no way to know, and no reason to care, that the data came from a nested GraphQL resolver three levels deep, or what actually broke on the way there.

This route also carries private, per-user data (email, subscription tier), which is exactly why its Cache-Control header defaults to private: a shared proxy or CDN caching this response under public would risk serving one user's profile to whoever else requests the same path next.

Three Rules the Skill Enforces on Every Route

1. Clean REST abstraction. Raw GraphQL errors, field names, err.message, and query strings never reach the REST consumer. If the upstream call fails, the adapter logs the real error server-side and returns a generic detail message, not a stack trace or the GraphQL error body.
2. Strict parameter validation. Every route parameter is validated with Zod before the GraphQL request fires (the generated adapter code is Node.js/Hono, so Zod, not Pydantic). A malformed userId never reaches the backend.
3. Configurable HTTP status code mapping. GraphQL error codes aren't standardized across APIs, so the mapping from a backend's actual extensions.code values to HTTP status (401, 403, 404...) is per-project config, not hardcoded, with an explicit 502 fallback for anything unmapped, instead of always returning 200 with an errors array the way a raw GraphQL passthrough does.

Where This Actually Gets Used

A Shopify integration is the clearest case: Shopify's Admin API is GraphQL-only, but most order-processing webhooks and third-party fulfillment tools expect REST. Wrapping the 5 GraphQL queries you actually need, order lookup, inventory check, fulfillment status, customer lookup, refund status, into fixed REST routes means your webhook handler stops carrying a GraphQL client dependency it barely uses.

A multi-step checkout mutation is the second common case. Instead of a frontend assembling a GraphQL mutation with a dozen nested inputs, POST /api/checkout accepts a flat JSON body, validates it, and executes the mutation server-side, with the validation errors coming back as RFC 7807 details instead of a GraphQL errors array the frontend has to parse.

Frequently Asked Questions