GraphQL requests

A GraphQL request is an HTTP request with a GraphQL body: a query document plus JSON variables, posted to a GraphQL endpoint. The editor adds a schema explorer built from introspection, a query builder, example variables and validation, so you can write a correct query without leaving the app. Everything else, from auth and scripts to settings and the response viewer, works exactly as for HTTP requests.

Create a GraphQL request

1. In the API client, click New › Other Protocols › GraphQL, or right-click a collection and choose Add Other Request › GraphQL. You can also run New GraphQL Request from Search Everything (⇧ ⌘ A).

   The new request uses POST, a public sample endpoint (https://countries.trevorblades.com/) and a starter query, so you can send it straight away.

2. Replace the URL with your endpoint, for example https://api.example.com/graphql.

3. Add any headers your API needs in Headers, and set auth in Authorization.

4. Open Body. The GraphQL body type is already selected. Write your query in Query and, if it declares variables, their values in Variables (JSON).

5. Press ⌘ ↩ or click Send.

12345

The GraphQL body: query and variables on the left, the schema explorer on the right.

1. GraphQL is sent as POST
2. GraphQL body type
3. Prettify the query
4. Variables as JSON
5. Fetch Schema runs introspection

×

GraphQL requests show a pink GQL badge in the sidebar. Any HTTP request can also use a GraphQL body: choose GraphQL in its Body tab.

What is sent

Cloak Proxy posts a JSON body with the query and, when the variables editor isn’t empty, the variables:

Request body

{
  "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
  "variables": { "id": "42" }
}

and sets Content-Type: application/json unless you set it yourself. In the editor, the same request looks like this:

Query

Query

query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

Variables (JSON)

Variables (JSON)

{ "id": "{{userId}}" }

{{variables}} work in the query and in the variables JSON. They are filled in before the variables are parsed, so the result must be valid JSON. If it isn’t, Cloak Proxy sends {} as the variables.

Explore the schema

1. Set the URL and any auth headers the endpoint needs.

2. Click Fetch Schema in the Schema panel. Cloak Proxy sends an introspection query to the URL and shows the number of types it found, or Couldn’t load the schema with the reason.

3. Browse the Query, Mutation and Subscription root types. Each field shows its arguments in parentheses and its type. Click the arrow next to an object field to see its fields, up to six levels deep. Hover a field to read its description.

4. Click Refresh to load the schema again after the server changes.

Deprecated fields appear dimmed.

What introspection sends

Fetch Schema sends the request’s Headers with the introspection query, but not auth from the Authorization tab. If your endpoint needs a token for introspection, add the Authorization header in Headers. The introspection request always goes through Cloak Proxy, so it appears in the traffic list.

Build a query by clicking fields

With a schema loaded, click a field name in the explorer to add it to the query. Cloak Proxy rewrites the document from the fields already selected plus the new one:

• Clicking a field under Query while the document is a query adds it to that query. Clicking a field under a different root type, such as Mutation, starts a new document of that type.
• An object field you add without picking any of its sub-fields gets __typename as a placeholder, so the query stays valid. Click a sub-field to replace it.
• The document is reformatted with two-space indentation.

The builder only adds fields. Add arguments, variables, aliases and fragments by hand after you finish picking fields, because clicking rebuilds the document from its field paths.

Variables, formatting and validation

Control	What it does
Prettify	Reformats the query with two-space indentation and one selection per line. Comments are removed, because formatting goes through the parsed document.
Example Variables	Appears once a schema is loaded. Fills Variables (JSON) with example values for every variable your query declares, based on their types.
Validation	Once a schema is loaded, problems in the query appear below the editor in orange, up to five at a time, with graphql-js style messages. It catches syntax errors, unknown fields, types, arguments and fragments, missing required arguments, undefined variables, missing or unexpected sub-selections, and operations the schema doesn’t support.

Validation is a quick check for typos, not a full GraphQL validator. It doesn’t check value types, field merging or overlapping fragments, so a query with no warnings can still be rejected by the server.

Read the response

The response appears in the standard response viewer. Most GraphQL servers answer 200 OK even when the query has errors, with an errors array in the body, so check the body rather than only the status. The JSON tree lets you filter keys and values and query the body. See Body viewers.

A test for a GraphQL response usually checks both:

Post-response script

pm.test("no GraphQL errors", () => {
  const body = pm.response.json();
  pm.expect(body.errors).to.be.undefined;
  pm.expect(body.data.user.email).to.eql("ada@example.com");
});

See Scripts and tests for the full pm API.

Run, share and generate code

GraphQL requests behave like HTTP requests everywhere else in the API client:

• The collection runner and cloakctl run them with their scripts and tests.
• Code shows the request as cURL or another language, with the GraphQL body as JSON. See Code snippets.
• They keep their GraphQL body when you export the collection to Postman, and a Postman request with a GraphQL body imports as a GraphQL request. See Import and export.

GraphQL subscriptions over WebSocket aren’t sent from the GraphQL editor. To test a subscription server, use a WebSocket request and send the protocol messages yourself.

GraphQL in captured traffic

The traffic inspector has a GraphQL tab for GraphQL requests your apps send. See WebSocket and GraphQL. To turn a captured GraphQL call into a saved request, see Capture to client.

Related

HTTP requestsSettings, response tabs and timing shared by GraphQL requests.

AuthorizationAdd tokens and keys to GraphQL requests.

WebSocket and GraphQLInspect GraphQL in captured traffic.

Scripts and testsAssert on data and errors in responses.