Exploring APIs with GraphiQL

Exploring an API You Have Never Seen

First day on a team, the backend lead sends you a URL and a login. No Postman collection, no generated docs, no time. Point a browser at the endpoint with GraphiQL mounted and the API starts describing itself.

GraphiQL is a browser application that talks to your live endpoint over the same GraphQL protocol everything else uses. Its documentation panel, completion, and signature hints are all built from an introspection request it fires the moment the page loads — the mechanics of that request are covered in introspection query mechanics. Nothing here is mocked or generated from a repo: you are querying production-shaped data through the real pipeline.

The exploratory loop is worth doing deliberately:

1. Type an opening brace and press Ctrl+Space. Completion lists the actual fields on Query — each entry annotated with its type.
2. Open the docs tree, search for a noun you recognize ("order", "customer"), and click into the type. The panel shows every field, its arguments, its nullability, and its deprecation state.
3. Pick a field, hover its arguments, and completion will insert them with placeholder values. Fill one in and press Ctrl+Enter.
4. Read the result pane: data on the left, execution timing below, and any errors with their path — exactly the response shape discussed in the standard error shape topic.

Two habits separate productive exploration from accidents. Start with read-only root fields; GraphiQL will happily run a mutation the moment you complete its name, and "just exploring" is a poor explanation for a created record. And prefer aliases when comparing variants of the same query — a: order(id: 1) and b: order(id: 2) in one document round-trip together instead of firing two requests.

When you know the API well, the workbench becomes a debugger: reproduce a client bug by pasting its exact operation and variables, toggle a field to see whether it is the one failing, and copy the whole request into a bug report.

What the Workbench Actually Gives You

The default GraphiQL layout hides its most useful parts. The parts that matter for daily work:

The variables pane deserves emphasis because beginners paste values inline and then discover the cost. With variables, the document is written once and the values change per run:

query RecentOrders($customer: ID!, $first: Int!) {
  orders(customer: $customer, first: $first) {
    id
    total
    status
  }
}

{ "customer": "c-1042", "first": 5 }

Same text every time — which means it can be cached, registered as a persisted query, pasted into a bug report, or shared with a teammate who only has to change the JSON. It also keeps literals out of the document, so an input containing quotes or newlines never corrupts the query.

A few operational details that surprise people: query history lives in your browser's localStorage, so it follows the machine and the browser profile, not your account — on a shared workstation it is a disclosure risk, and clearing site data erases it. The docs panel reflects whichever schema the IDE last fetched; after a server deploy, use the reload-schema control to re-run introspection rather than trusting a stale tree. And because completion quality is only as good as the schema behind it, an endpoint with introspection disabled renders GraphiQL nearly useless — the editor still accepts text, but the panel and hints go quiet.

Shipping the IDE Without Shipping the Risk

GraphiQL is a development tool that executes arbitrary queries with whatever credentials the caller presents and renders a complete map of your schema. Left on a public production endpoint, it hands an attacker the two things they want first: documentation and a console.

The exposure is really introspection plus execution. Disabling introspection (see schema exposure control) collapses the docs panel and the completion, which neuters the IDE for legitimate users too — so the practical postures are:

• Default: development and staging only. Most servers make this a flag. GraphQL Yoga and express-middleware setups expose GraphiQL behind an option you enable per environment; Apollo Server serves a landing page whose embedded graph-explorer mode you choose deliberately rather than by accident.
• Internal production: gate it, do not delete it. On an internal API behind a VPN or an SSO-protected admin gateway, leaving GraphiQL up saves the on-call engineer from reconstructing requests at 3 a.m. Gate by network or by an admin role, and keep introspection aligned with that gate.
• Public production: off. Public callers should get their schema from a published artifact (SDL or introspection JSON exported at release time) that documentation sites and codegen consume, not from a live self-describing endpoint.

Alternatives worth knowing when the decision is "how does this team work without it": IDE extensions (the VS Code GraphQL extension runs operations from your workspace using the checked-in schema), standalone clients such as Insomnia or Bruno that import SDL, and hosted explorers that require a reachable endpoint — those last still need the same exposure decision as GraphiQL itself.

One more production detail: GraphiQL's history, headers, and tokens sit in browser storage. On shared or managed machines, that makes the header pane a place where bearer tokens outlive the session. Prefer short-lived tokens for exploration, and remember that everything you paste there is per-browser, not per-account.

Interview framing: the good answer to "should GraphiQL be enabled in production?" is conditional — distinguish public from internal, tie the decision to introspection exposure, and name the artifact-based alternative for public consumers. Answering "never, it's a dev tool" or "always, it's convenient" both skip the actual tradeoff.