GraphQL

Choose GraphQL as the body type. The method switches to POST, because every GraphQL server takes one and almost none take a GET with a body.

The query goes in the ordinary body editor — it is still the body, and giving it a second editor would mean two places to look for the same text.

Variables

The Variables panel takes a JSON object, checked as you type. A malformed object is the single most common GraphQL mistake, and the server's answer to it is a schema error pointing nowhere near the actual problem — so it is caught before the request is sent.

{ "id": 4, "first": 10 }

{{variables}} work inside both the query and the variables.

The schema

Fetch schema runs an introspection query against the current URL. Once it has one, three things change.

Completion. Type inside a selection set and the fields offered are the fields of that type — an Order has a total, a User does not. It follows lists and non-null decoration, so orders: [Order!]! completes as an Order. It also works inside a fragment, rooted on the fragment's own type.

Docs. A navigable view of the schema: click a field's type to go into it, and the breadcrumb trail back out — every step clickable, because following references three types deep and then wanting the first one is the normal way to read a schema. Click a field name to insert it into the query at the caret.

Prettify. Lays the document out: two-space indent, one field per line, arguments left where you wrote them.

The schema is discarded when the URL changes, so you never complete against a different endpoint's fields.

Several operations

A document may define more than one. When it does, an operation picker appears and the chosen name is sent as operationName.

With a single operation there is no picker, and no name is sent — naming an operation the server did not ask about is a good way to get a confusing error back.

Fragments are not operations, wherever you put them:

fragment UserBits on User { id name }

query GetUser {
  user { ...UserBits }
}

That is one operation, and it is treated as one.

Errors

GraphQL reports failure as HTTP 200 with an errors array. That is the whole problem with debugging it through an ordinary HTTP client — everything looks fine.

A response carrying errors is called out with a banner, whatever the status code. Partial success — data and errors together — is shown as exactly that, rather than as a clean result.

From a script:

sw.test("no GraphQL errors", () => {
  sw.expect(sw.response.json().errors).to.equal(undefined)
})

Subscriptions

Subscriptions are a stream, not a request, so they run over WebSocket rather than HTTP. Both protocols are supported:

graphql-transport-ws	Apollo Server 4, Yoga, current Hasura.
graphql-ws	Apollo Server 2 and 3, older Hasura.

The names are a genuine trap: the subprotocol graphql-ws is the older protocol, while the library called graphql-ws implements the newer one. Choosing the wrong one gives you a socket that opens, handshakes, and then silently never delivers anything — so if a subscription connects and nothing arrives, try the other protocol first.