Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

GraphiQL, Playground and Sandbox Tools

Compare GraphiQL, GraphQL Playground, Apollo Sandbox, Insomnia and Postman: the editor, variables and headers panes, history, the schema explorer, embedding, and turning tools off in production.

A GraphQL server is just an HTTP endpoint, so you could talk to it with curl. Nobody does for long. The real power of the typed, introspectable schema shows up in tools: an editor that auto-completes field names, a documentation panel generated from the schema, a place to keep variables and headers, and a history of what you tried. These tools are how most people first meet GraphQL, and they are a big part of why teams enjoy working with it.

This lesson tours the common tools, explains the panes you will see in nearly all of them, shows what is happening on the wire when you press the "play" button, and covers the part people forget: what to do with these tools in production. Nothing on this site can launch a real server or a real IDE, so the runnable examples are stand-ins: a loopback endpoint and a miniature explorer that behave like the real thing for the idea being taught. Real tool configuration appears in read-only blocks.

What a GraphQL tool gives you

Editor Auto-complete and error squiggles.
Docs Browse types from the schema.
Variables and headers Keep inputs apart from the query.
History Re-run earlier queries.

All of it is built on introspection.

1 / 2

The main tools

GraphiQL is the reference IDE, maintained under the GraphQL Foundation. It is a React component, which means servers can embed it at a URL (often the same /graphql path opened in a browser) and you can also embed it in your own documentation or admin pages. GraphQL Yoga serves it by default in development, and many servers and frameworks offer it.

GraphQL Playground was a popular alternative with tabs and a dark theme. It is no longer actively developed, and most servers that used to ship it have moved to GraphiQL or to Apollo's sandbox. You will still meet it in older projects and tutorials, so it helps to recognize it; for new work prefer one of the other tools.

Apollo Sandbox is a hosted explorer from the Apollo team. The page runs in your browser and connects to your server's URL, so a server on localhost works. Apollo Server shows it as its landing page in development. It adds features such as saved collections and a field-usage view.

General API clients such as Postman, Insomnia and Bruno have a GraphQL mode: you point them at the URL, they fetch the schema by introspection, and give you auto-complete next to your REST requests, environments and saved collections. They are a good fit when a team already keeps its API requests there, and when you need to script requests for tests.

The tools change quickly, so check each project's documentation for what is current. What does not change is the shape of the workflow, which the next sections describe.

The panes you will see

Almost every GraphQL tool has the same layout:

  • Query editor. Type { and the tool suggests the root fields from the schema. Hover a field to see its type and description. Errors such as an unknown field or a missing required argument appear before you send anything, because the editor validates against the schema it fetched.
  • Variables pane. A JSON object holding the values for $variables in your query. Keeping values here, instead of pasting them into the query text, is how real clients work (see Variables, Directives and Operation Names).
  • Headers pane. Extra HTTP headers, most often Authorization: Bearer <token>. Without it, anything behind authentication comes back as null with an error.
  • Response pane. The JSON data and errors from the server.
  • Docs or schema explorer. A browsable tree of types, fields, arguments and descriptions. It is generated from introspection (see Input Types, Custom Scalars and Introspection), so the descriptions you write in the schema ("""...""") become documentation.
  • History and tabs. Past operations to re-run, and several queries at once.
  • Prettify and copy-as-cURL. Prettify reformats the query. Copy-as-cURL turns the request into a command line you can paste into a bug report or a script.

Name your operations (query BookPage { ... }). History lists, server logs and error reports all show the operation name, and tools that hold several operations in one tab need names to let you pick which one to run.

What happens when you press play

Nothing magic. The tool performs a normal GraphQL-over-HTTP request, as described in GraphQL over HTTP:

HTTP
POST /graphql HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ...

{
  "operationName": "BookPage",
  "query": "query BookPage($id: ID!) { book(id: $id) { title author { name } } }",
  "variables": { "id": "b1" }
}

On start-up the tool also sends an introspection query (a large query for __schema) so that it knows which types exist. That is why the explorer shows nothing, and the editor cannot auto-complete, when introspection is disabled on the server. Some tools let you load a schema from a .graphql file or a URL instead.

Stand-in: an endpoint and a tiny explorer

The stand-in below starts a real HTTP server on the loopback address and plays the role of the server. It understands one query shape (the real engine is replaced by a lookup), supports Authorization, and answers a toy introspection request. A short "explorer" function then does what GraphiQL does: fetch the schema, list the fields, send a query with variables and a header, and remember the history.

Node.js A server, an explorer and a history list

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Without the header, secret comes back null plus an error, exactly the symptom you see in GraphiQL when you forget to set Authorization in the headers pane. The history list holds the operation name, which is why naming operations pays off.

Embedding GraphiQL

You can host GraphiQL yourself, in development builds of your own server or in documentation. The usual approach is to serve a small HTML page that loads the GraphiQL bundle and points it at the endpoint. The shape below is read-only and simplified; the exact script URLs and options change between versions, so copy the current snippet from the GraphiQL documentation.

HTML
<div id="graphiql" style="height: 100vh;"></div>
<script type="module">
  // Load GraphiQL and React from a CDN or your bundler (see the GraphiQL docs for current URLs).
  import { createGraphiQLFetcher } from "@graphiql/toolkit";
  const fetcher = createGraphiQLFetcher({ url: "/graphql" });
  // Render <GraphiQL fetcher={fetcher} /> into #graphiql
</script>

Server libraries usually do this for you with one option. For example, GraphQL Yoga has a graphiql setting, and Apollo Server chooses its landing page through plugins.

Disabling tools in production

Interactive tools are a gift to developers and a gift to attackers too. Before you ship:

  • Turn off the embedded IDE on public endpoints, or put it behind authentication and an internal network. Most servers have a switch, and some pick a safer default when NODE_ENV=production; verify the behavior of the version you run.
  • Decide about introspection. Introspection powers the tools, but it also hands over a full map of the schema. Public APIs that want to be explored leave it on; private application APIs often turn it off in production and let developers use a schema file or a staging server. Remember that turning introspection off is not access control: attackers can still guess field names, and servers sometimes leak suggestions in error messages ("Did you mean secret?"). Authorization and query limits (see Query Depth, Complexity and Other Attacks) do the real work.
  • Protect credentials. A shared tool environment that stores bearer tokens is a secret store. Do not paste production tokens into hosted tools, and rotate tokens that ended up in a screenshot or a shared collection.
  • Use a staging endpoint with realistic data for exploration, and keep the production endpoint for applications.

Stand-in: a production switch for introspection

This stand-in shows the effect of the switch. The same handler either answers __schema queries or rejects them, depending on an environment flag. Notice that ordinary queries keep working either way.

Node.js Introspection on in development, off in production

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

With introspection blocked, an IDE connected to production would show an empty docs panel and no auto-complete, which is the intended effect. Applications keep working because they send their own known queries.

Choosing a tool

  • Learning or daily development: the IDE that comes with your server (GraphiQL or Apollo Sandbox) is zero setup.
  • Team workflows with environments, secrets and scripts: Postman, Insomnia or Bruno, since you probably already use one for REST.
  • Documentation: embed GraphiQL against a read-only sandbox.
  • Automated checks: not a GUI at all, but tests (see Testing GraphQL APIs) and schema diffs in CI.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does a GraphQL IDE show an empty docs panel when introspection is disabled?

    Tools read the schema by asking the server about itself (__schema). Without it, they have nothing to render unless you load a schema file.
  2. 2. Where should an access token go when testing a protected query in GraphiQL?

    The headers pane sets HTTP headers on the request. Tokens in URLs or query text leak into logs and history.
  3. 3. Which statement about GraphQL Playground is the most accurate?

    Playground still appears in older projects, but most servers moved to GraphiQL or Apollo Sandbox.
  4. 4. Is disabling introspection enough to protect private fields?

    Hiding the schema is obscurity, not access control. Fields must still check permissions in resolvers or services.
  5. 5. What is a good reason to name every operation (query BookPage { ... })?

    Names have no effect on speed. They help people and tools tell operations apart.

Summary

  • GraphiQL is the official IDE; Playground is older and no longer actively developed; Apollo Sandbox is a hosted explorer; Postman, Insomnia and Bruno have GraphQL modes.
  • Nearly all tools share the same panes: editor, variables, headers, response, schema docs, history and copy-as-cURL.
  • Pressing play sends an ordinary POST with query, variables and operationName, preceded by an introspection query that powers auto-complete and docs.
  • Name your operations, keep values in the variables pane and tokens in the headers pane.
  • Turn off or protect embedded IDEs in production, decide about introspection deliberately, and remember that hiding the schema is not authorization.

Next, set up a real server yourself in Setting Up a Server: Express, Apollo Server and Yoga.