GraphQL Playground: Test APIs in Your Browser
Run GraphQL queries, mutations, variables, and schema introspection against any CORS-enabled endpoint — no desktop app required.
Table of Contents
GraphQL shines when you can ask an API exactly the fields you need — and it frustrates when you need a heavy IDE just to try one query. The GraphQL Playground lets you point at an HTTP endpoint, write a query or mutation, add JSON variables and headers, then execute the request from the browser.
The tool ships with a public demo endpoint (https://countries.trevorblades.com/) and a sample countries query so you can click Execute immediately. From there you can swap in your own URL, validate syntax before you hit the network, format messy operations, and fetch a readable schema snapshot via introspection.
This guide covers how the playground works, what GraphQL concepts it maps to, and when a browser client is enough versus when you need a server-side runner.
Why Use GraphQL Playground?
- Zero install. Paste an endpoint and run. No GraphiQL desktop build, no npm GraphQL client, no Postman collection to maintain for a one-off check.
- Syntax before the round trip. Validate parses your document with the official graphql library so missing braces and invalid operations fail locally.
- Readable operations. Format reprints the AST with consistent indentation — useful when you paste a minified query from logs.
- Schema discovery. Schema sends an introspection query and summarizes types, fields, and arguments so you can explore APIs you did not write.
- Auth and variables. Optional JSON Headers (Bearer tokens, custom keys) and Variables ($id: ID!) match how production clients actually call GraphQL.
- Privacy-friendly for the editor. Your query text lives in the page until you execute. The request still goes from your browser to the endpoint — it is not a hosted proxy for secret APIs.
Key Features
| Feature | What it does |
|---|---|
| Endpoint URL | Target any GraphQL HTTP server that accepts POST with { query, variables } |
| Query editor | Full operation documents: queries, mutations, and subscription syntax |
| Validate | parse() plus a check that at least one operation exists |
| Format | print() the AST for consistent layout |
| Execute | fetch POST, pretty-print JSON data / errors |
| Schema | Introspection of query/mutation/subscription roots and types |
| Variables | JSON object merged into the request body |
| Headers | Extra HTTP headers (for example Authorization) |
- Responses include HTTP status when the server answers; GraphQL errors still appear in the JSON errors array even on HTTP 200.
- Invalid JSON in Variables or Headers is rejected before the request is sent.
- CORS failures surface a clear message: many private APIs block browser origins. Public APIs that send Access-Control-Allow-Origin work out of the box.
How to Use
- Open the GraphQL Playground. The countries demo endpoint and query are prefilled.
- Click Execute. You should see JSON with country code, name, capital, and emoji. Copy the result if you need it in a ticket or test fixture.
- Change the GraphQL Endpoint URL to your CORS-enabled server. Keep the path your API uses (/graphql, /api, or a full URL).
- Edit the operation. Use Validate after each structural change, then Format if the document is hard to read. Expand Variables and Headers when the operation needs $variables or auth.
- Click Schema to introspect. Skim the generated summary for type names and fields, then write a tighter query. Clear resets the response panel when you start a new experiment.
If execute fails with a CORS note, the API is refusing the browser. Use a backend script, a desktop client, or a proxy you control — the playground cannot bypass that policy.
Understanding GraphQL in the Playground
A GraphQL HTTP request is usually a JSON body with query (a string) and optional variables (an object). The playground builds that body for you. The server returns { "data": … } on success and may include { "errors": [ { "message", "locations" } ] } when the document is valid GraphQL but fails at runtime (unknown field, auth, nullability).
Queries read data. The demo countries { code name } is a selection set: you name fields, the server fills them. Nested objects work the same way — indent fields under a parent.
Mutations change data. Syntax is the same document; you typically pass variables so you do not hard-code IDs in the operation string:
mutation UpdateTitle($id: ID!, $title: String!) {
updatePost(id: $id, title: $title) { id title }
}
Put { "id": "1", "title": "Hello" } in Variables. Headers can carry Authorization: Bearer … as JSON: { "Authorization": "Bearer TOKEN" }.
Subscriptions are often WebSocket-based. This playground posts over HTTP, so you can validate and format subscription documents, but live event streams need a dedicated client. Treat subscription syntax here as a lint step, not a live feed.
Introspection asks __schema for root types and a list of types with fields and arguments. Servers may disable introspection in production. If Schema returns an error, the API is locked down — rely on published SDL or generated docs instead.
CORS is the main browser constraint. The playground runs fetch from onlinetoolsforge.com (or localhost in dev). If the server does not allow that origin, the browser blocks the response. That is a feature of the web platform, not a bug in the tool.
Practical Use Cases
Smoke-test a public GraphQL API
You found a countries, GitHub (via a CORS-friendly proxy), or CMS GraphQL URL in docs. Paste it, run the documented example, then strip fields until the payload is small enough to paste into Slack. Schema introspection tells you which types exist when the README is stale.
Debug a failing client query
Copy the operation from your app logs. Validate locally to separate parse errors from server errors. If the document is valid but errors mention an unknown field, fetch Schema and confirm the type still exposes that field. Format the query before you commit it so code review is readable.
Prototype variables and headers
Backend tickets often say “call this mutation with a JWT.” Put the mutation in the editor, variables in JSON, and the Bearer header in Headers. Iterate without rebuilding a mobile or SPA client. Do not paste production secrets into a shared machine; use a throwaway token.
Teach GraphQL selection sets
New teammates can start from the countries query, add emoji, remove capital, and watch the JSON shape change. That feedback loop is faster than reading the spec. Pair it with GraphQL Formatter when you need to pretty-print a query outside the playground.
Best Practices
- Prefer variables over string concatenation. Keep IDs and user input in the Variables JSON so the operation stays a static document.
- Validate before Execute on large documents. A parse error is cheaper than a failed network round trip.
- Treat CORS as a product constraint. For authenticated internal APIs, run queries from CI or a backend. Use the playground for public or explicitly CORS-open endpoints.
- Never commit live tokens into shared notes. Rotate anything you typed into Headers on a demo.
- Introspect only where allowed. Production lockdown is normal; keep a checked-in schema file as the source of truth.
- Copy responses for fixtures. The formatted JSON is ready for mock servers and contract tests.
When you need a query assembled from fields rather than typed by hand, try the GraphQL Query Builder. When the API is stable and you want TypeScript types from the schema, use GraphQL to TypeScript.
Ready to run a document against a real endpoint? Open the GraphQL Playground, hit Execute on the demo, then point it at your CORS-enabled API.
Related Tools You Might Like:
- GraphQL Formatter — beautify and inspect GraphQL documents
- GraphQL Query Builder — assemble queries from fields without fighting braces
- GraphQL to TypeScript — generate types from GraphQL operations
Happy querying!