Why does a GraphQL explorer keep variables and HTTP headers in panes separate from the document?

## Three panes, two layers An explorer's layout is a picture of the request it is about to send, and that request has two layers stacked on top of each other. The inner layer is the **GraphQL request**. The GraphQL over HTTP specification names its parameters: `query` — the executable document text, whatever operations it contains; `variables` — a map of values for the variables the operation declares; `operationName` — which operation to execute when the document defines more than one; and `extensions` — a free map for protocol extensions. The document pane and the variables pane are editors for two of these; the explorer's "which operation" selector supplies the third when it is needed. The outer layer is **HTTP**. Authorization credentials, a client name and version, trace context, a request id — these are headers on the HTTP request. Nothing in the GraphQL request carries them, and a server reads them from the transport, not from the document. That is why the headers pane is separate from the other two rather than being another key you type into the variables JSON. A candidate who can say which pane feeds which layer has the whole model, and it immediately explains a class of confused debugging: an authorization token typed into the variables pane does nothing, because no operation declares a variable for it and the server was never going to look there. ## What the variables pane actually is It is JSON, and its keys are the variable names **without** the `$` sigil. The declarations live in the document, on the operation: ```graphql query ReleaseCredits($releaseId: ID!, $first: Int! = 25) { release(id: $releaseId) { title credits(first: $first) { role person } } } ``` ```json { "releaseId": "rel_9f3c14", "first": 12 } ``` The declared types are load-bearing. Before execution begins, each supplied value is coerced against the type its variable declares: a JSON string handed to an `Int!` variable, or a missing value for a non-null variable with no default, fails the request outright — no field resolves, and the response carries errors with no `data` key rather than a partly-filled object. A default in the declaration (`$first: Int! = 25`) applies when the variables map omits the key; note that explicitly supplying `null` is not the same as omitting the key, which trips people up when an explorer's variables pane is left with a leftover `"first": null`. ## Why not just paste the value into the document? An explorer lets you write `release(id: "rel_9f3c14")` directly, and for a one-off poke that is fine. As a habit it costs four separate things. **Escaping.** Values become part of the document's syntax. A track title containing a quote or a newline has to be escaped by hand, correctly, every time. A variable value is JSON that never touches the document grammar. **Type checking.** A variable is declared with a type and coerced against it, and a mismatch is caught before execution. A literal spliced into the document is checked as a literal, and the failure arrives less usefully. **Document identity.** With variables, one document text serves every call; with literals, every distinct value produces a different document. Anything that keys on the document text — a hash used to look up a registered document, a grouping dimension in logs and metrics — fragments into one entry per value, which is how a dashboard ends up with thousands of one-request "operations". **Reuse.** The document you tested in the explorer is the exact document the application ships, with only the values differing. A document with a literal embedded in it is not the one your application sends, and that difference is where a green explorer run stops predicting anything. ## Headers, and the cookie trap The headers pane is where credentials go, and it has one wrinkle worth knowing: an explorer running as a page in a browser cannot set every header. `Cookie` in particular is a header the browser controls — a page's fetch cannot set it directly, and whether the browser attaches the cookies it already holds depends on how the request was issued and on the origin. The practical consequence is that a browser-hosted explorer is often authenticated by a session cookie the browser is attaching for you, invisibly, with nothing in the headers pane to show for it. That is a habit worth building: when a request works in the explorer, read the headers pane *and* remember what the browser is adding underneath it, because that combination is what actually authenticated the call — and it is rarely what an application sends.