Sending GraphQL queries
Write GraphQL operations with schema-aware completion and send them with variables.
Overview
A GraphQL body holds an operation, the variables it uses and, when the document defines more than one operation, which one to run. Relay sends them as a JSON object with query, operationName and variables members, leaving out an empty operation name and blank variables:
{
"query": "query User($id: ID!) { user(id: $id) { name } }",
"variables": { "id": "42" }
}Relay also sets Content-Type to application/json and Accept to application/graphql-response+json, application/json, unless you add those headers yourself.
When you load the server's schema, the editors suggest fields, arguments, types and variables as you type, and Relay can fill in an operation's variables for you.
Relay sends GraphQL in the body of a request. It doesn't send operations as query parameters of a GET request, and it doesn't support subscriptions.
Create a GraphQL request
- Create a request and enter the GraphQL endpoint's URL, such as
https://api.example.com/graphql. - In the request editor, click Body, or press Command-5.
- Click the menu at the top of the tab and choose GraphQL.
If the request was a GET request, its method changes to POST.
The editor shows the query above its variables. To give either one more room, drag the Variables bar up or down.
Write the operation
Enter the operation in the Query editor:
query User($id: ID!) {
user(id: $id) {
name
email
}
}If the document has more than one named operation, a menu replaces the Query label. Choose the operation to run from it. A document with a single operation doesn't need one chosen.
Get the server's schema
Relay fetches a schema only when you ask for it. Click Fetch Schema at the end of the bar above the Query editor, then choose Fetch Schema. Relay sends the introspection query to the request's URL with the request's headers, auth, cookies and settings. It doesn't run the request's scripts or record the introspection request in history.
When the schema arrives, the menu shows how long ago it was fetched. To fetch it again after the server changes, open the menu and choose Fetch Schema Again.
If the server turns introspection off, load the schema from a file instead: open the menu, choose Load Schema from File…, and select a JSON file holding an introspection result.
Requests in the same workspace that send to the same URL share a schema. Relay keeps it until you quit, or until you choose Forget Schema from the menu.
If the schema can't be fetched, the menu shows Schema Failed. Hold the pointer over it to see why.
Complete fields and variables
As you type in the Query editor, Relay suggests what can come next: fields, arguments, input fields, enum values, fragments, directives, types, keywords and the operation's variables. With a schema loaded, the suggestions follow it. To show suggestions without typing, press Option-Escape.
The Variables editor suggests the selected operation's variable names as keys, the fields of input types inside them, and the values an enum or a Boolean can take.
Fill in the variables
Write the variables as a JSON object in the Variables editor:
{
"id": "42",
"limit": {{pageSize}}
}Variables can contain tokens such as {{pageSize}}, even where JSON expects a number or an object, as long as the result is a JSON object once Relay replaces them. Otherwise the request isn't sent, and its status explains what's wrong.
To start from the operation's variable definitions, click the Generate from Operation button in the Variables bar. Relay adds a key for each variable, with its default value or a placeholder for its type, such as "" for a string or 0 for a number, and keeps any values you've already entered.
Read errors in the response
A GraphQL server usually reports errors with a 200 status. When a response to a GraphQL request contains an errors array, the response inspector's Body tab shows them in a banner above the body, with each error's message and, when there is one, the path it applies to. If there are more than three, click Show All to see the rest.
See Also
- Adding a request body: Send text, JSON, form fields or files with a request.
- Inspecting responses: Read a response's status, body and headers, and copy or save what you need.
- Using variables: Insert values into requests with
{{name}}tokens and see where each value comes from. - Importing Postman collections and environments: Bring Postman collections, with their folders, auth and scripts, and Postman environments into Relay.