Skip to content

GraphQL

GraphQL in Restura is HTTP underneath, but the editor knows the spec: it can introspect the endpoint, hint completions from the schema, and run subscriptions over WebSocket (graphql-transport-ws or legacy Apollo subscriptions-transport-ws) or Server-Sent Events (graphql-sse).

  • Introspection — “Refresh Schema” against any GraphQL endpoint; Restura fetches the schema and uses it for completion and validation. The query asks for the full October 2021 spec surface — deprecated arguments and input fields, scalar specifiedByURL, repeatable directives and @oneOf input objects — and steps down automatically when a server rejects those fields: first without @oneOf (for servers that implement the 2021 spec but not @oneOf), then the classic introspection query. Other errors, such as introspection being disabled, are shown as-is without a retry — in the schema explorer, and as an Introspection failed — autocomplete off hint (with Details) above the editor. Refresh always re-fetches, ignoring the cached schema. Introspection only runs when you ask for it (it carries the request’s credentials); with no schema the hint reads No schema — autocomplete off, with Introspect and load-file shortcuts. The schema explorer strikes through deprecated fields (reason on hover) and tags @oneOf / @specifiedBy types; the SDL download keeps all of it. Runs through the shared proxy (so it carries the request’s auth + TLS/proxy config and works on desktop, where a direct fetch is CSP-blocked).
  • Load a schema by hand — for endpoints with introspection disabled. Load (next to the SDL download in the query toolbar, or the upload icon in the schema explorer) accepts a .graphql / .graphqls / .gql SDL file, pasted SDL, or an introspection JSON result ({ "data": { "__schema": … } } or { "__schema": … }). Parse errors are shown with their line and column. The schema is saved on the request — it survives reload and travels with the request when saved to a collection or exported to OpenCollection — and drives completion, validation and the schema explorer (marked IMPORTED). Refresh asks before replacing an imported schema with an introspection result, and keeps the imported one if introspection fails.
  • Query / Mutation / Subscription — the operation type is read from the parsed document, so a leading # comment or fragment definition never hides a subscription, and shorthand { … } counts as a query. Queries and mutations POST over HTTP; subscriptions open a long-lived connection using the request’s subscription Protocol (see below). The send button says which: Run query, Run mutation or Subscribe.
  • Multiple operations — when a document defines more than one operation, chips above the editor list them (with a query / mutation / subscription icon). The selected operation is saved on the request (and carried through OpenCollection export/import) and sent as operationName — over HTTP and in the subscription payload of every subscription protocol (graphql-transport-ws subscribe, legacy start, graphql-sse POST body). Picking an operation narrows the variables JSON to that operation’s variables, keeping values you already typed for names they share. With no selection, the first operation runs.
  • GET or POST — click the method chip in the URL bar to switch. POST (the default) sends the JSON body { query, variables, operationName }. GET sends the same fields URL-encoded as query, variables, operationName and extensions query parameters, per GraphQL over HTTP, which is useful for CDN-cached queries. The full query text is always sent — persisted queries (sending only a sha256Hash in extensions.persistedQuery) are not supported. GET works for queries only: Restura refuses to send a mutation or subscription over GET and asks you to switch back to POST. The chip turns red when that applies. The method is saved on the request and exported as graphql.method in OpenCollection.
  • Accept header — requests send Accept: application/graphql-response+json, application/json;q=0.9 (GraphQL over HTTP) unless you set your own Accept header. Documents that use @defer or @stream also advertise multipart/mixed;deferSpec=20220824.
  • @defer / @stream (incremental delivery) — multipart/mixed responses are parsed and their parts merged into a single { data, errors, extensions } result. Both the deferSpec=20220824 format (Apollo, graphql-yoga) and the newer pending/completed format are supported. A notice above the body shows how many parts were merged. Test scripts and history see the merged JSON rather than the raw multipart body.
  • Variables — separate JSON editor; resolves environment placeholders ({{userId}}).
  • {{variables}} in the URL — autocompleted and highlighted (unresolved names are flagged). Resolved from the active environment and globals at send time.
  • Authentication — the same auth schemes as HTTP. Most teams ship a Bearer token here.
  • Headers — bulk edit (one key: value per line, // to disable a row) and an optional description per row; header values resolve {{variables}}.
  • Scripts — the Scripts tab holds pre-request and test scripts, run for queries and mutations exactly as for HTTP (see Scripts). They don’t run for subscriptions.
  • Code — the Code button generates cURL, JavaScript (fetch) or Python (requests) for the operation. Headers are used as typed: {{variables}} stay unresolved and Auth-tab credentials are not included.
  • Subscriptions — over WebSocket (graphql-transport-ws, or Apollo’s legacy subscriptions-transport-ws) or graphql-sse, picked per request with the Protocol selector in the Messages tab (default Auto). Live events stream into the response panel; the Messages log can be searched, filtered by direction, frozen, exported and cleared. On desktop the socket is tunnelled over the WebSocket IPC bridge and graphql-sse over the SSE IPC handler (the packaged CSP blocks renderer ws:/wss:/http:), with header auth carried on the handshake.

Query and mutation documents go through the shared HTTP proxy (POST, or GET for queries), same as any other HTTP request. A subscription is different: Restura opens a long-lived connection using the request’s Protocol setting (saved on the request and carried through OpenCollection export):

ProtocolWireNotes
Auto (default)WebSocketOffers both graphql-transport-ws and graphql-ws in Sec-WebSocket-Protocol and speaks whichever the server selects (one handshake). A server that selects none is treated as graphql-transport-ws.
graphql-transport-wsWebSocketThe modern graphql-ws protocol.
subscriptions-transport-wsWebSocket, subprotocol graphql-wsApollo’s legacy protocol (connection_init → start → data/error/complete, ka keep-alives ignored).
graphql-sseHTTP POST → text/event-streamgraphql-sse distinct connections mode only (single-connection mode isn’t supported). Streams through the same path as the SSE feature: the Worker proxy on web, the SSE IPC handler on desktop — so the SSRF policy applies. Request headers are sent as real HTTP headers.

WebSocket URLs are derived from the request URL by swapping the scheme (http(s):// → ws(s)://); graphql-sse does the reverse. The negotiated protocol is shown on the connected line of the response panel.

  • Lifecycle — the response panel steps through connecting → connected → a stream of data messages → complete (or error if the server rejects the connection or the document). A 30-second connection timeout aborts the attempt if the server never acknowledges.
  • Same auth as queries — every protocol uses the tab’s effective auth: a request with no auth of its own inherits its folder’s or collection’s, and {{variables}} are resolved in the URL, headers, and auth fields. An API key set to Query Params is appended to the socket (or graphql-sse request) URL.
  • Web — uses the browser’s native WebSocket. Browsers can’t set custom handshake headers, so auth rides the connection_init payload instead (Restura’s request headers become connectionParams); graphql-sse sends it as real HTTP headers through the proxy. Keychain-stored secrets and secret variables can’t be resolved on the web; Restura warns and opens the subscription without them rather than sending a placeholder. The WebSocket connects browser-direct, so the Worker’s SSRF guard doesn’t apply: Restura refuses loopback, private-network and cloud-metadata targets unless Settings → Security → Allow private / internal IPs is on.
  • Desktop — the socket is tunnelled over the WebSocket IPC bridge, which can set real handshake headers, so auth is sent as actual headers on the WS upgrade request and also in connection_init. Keychain-stored secrets (and secret variables) are resolved by the desktop app’s main process at connect time and sent as handshake headers only (or graphql-sse request headers) — their plaintext never reaches the UI, so it isn’t copied into connection_init. If a keychain secret can’t be resolved (e.g. it was deleted), the subscription fails instead of connecting unauthenticated, and handshake redirects aren’t followed for these connections.
  • Switching operations — selecting a different operation in a multi-operation document disconnects the running subscription; the chosen operation’s name rides the subscription payload as operationName on whichever protocol is selected.
  • Syntax highlighting + bracket matching.
  • Prettify — the button in the editor toolbar reformats the document (there is no keyboard shortcut for it).
  • Download SDL — the SDL toolbar button saves the loaded schema (introspected or imported) as schema.graphql.
  • Click-to-insert — clicking a field in the schema explorer appends its name on a new line at the end of the query and switches to the Query tab.
  • Metadata chips — the Query tab is tagged with the selected operation’s type, Variables and Headers show how many variables (keys in the variables JSON) and enabled headers are set, and the query toolbar shows the document’s size in bytes.
  • Errors on a 2xx — a successful (2xx) response whose body contains a GraphQL errors array raises an error toast, and every entry is listed in the response panel’s Errors tab (with locations marked in the editor).
  • Inline error markers when the document doesn’t validate against the schema.
  • Operation chips to switch between operations when the document defines several.
  • Cmd+Enter / Ctrl+Enter inside the query editor runs the operation under the cursor (selecting it); elsewhere it runs the selected operation.
  • If the server gates introspection in production, use Load to paste the SDL or load a schema file (or an introspection JSON exported from a staging server) to keep completions and validation working.
  • Subscribing over ws:// / http:// with auth configured asks for confirmation first on every platform, because the credentials would travel in cleartext.
  • Subscriptions count as a long-lived response — see also SSE and WebSocket for raw transport access.
  • For load-style testing, drive a GraphQL collection through the CLI — same wire format as HTTP, JUnit / HTML / JSON reporters included.
  • To try GraphQL against a real server locally, echo-local serves query/mutation over its HTTP endpoint (http://localhost:8080/graphql, POST — already in the generated collection with working auth) and a subscription endpoint over WebSocket (ws://localhost:8085/graphql, subscription { tick(count) { n timestamp } }) that you drive manually. See Local test stack.
  • Authentication — Bearer is most common.
  • Local test stack — echo-local’s GraphQL query/mutation and subscription endpoints, plus ports and credentials for every other protocol.
  • Workflows — chain a mutation and use the result in a query.
  • Import & export — move GraphQL requests between Restura, Postman, Insomnia, and OpenCollection.