GraphQL action

Runs a query or a mutation against a GraphQL API and makes the data it returns available to later steps. In the action picker it is GraphQL, under General Actions. It needs a GraphQL connection.

Reach for it rather than an HTTP Request whenever the service speaks GraphQL. The step reads the API's schema, so it can check your query as you write it, give later steps the exact shape of what the query returns, and open GraphiQL for exploring the API.

Fields

Field	Required	Description
Connection	Yes	The GraphQL API to call.
Query	Yes	The GraphQL document to run: one query or mutation, or several, each named. It is checked against the API's schema as you type.
Operation Name	When the query has more than one operation	Which of the query's operations runs. Appears only when the query holds more than one.
Variables	When the query declares required variables	A value for each variable the query declares. Each can come from an earlier step or be typed. Appears once the query declares a variable.
Headers	No	Headers sent with this step's call, after the API's own. One with the same name as a header on the connection replaces it for this step.

Advanced

Field	Description
On GraphQL Errors	What happens when the API answers with errors. Fail the Step, the default, fails it with the API's messages and the paths they apply to. Continue With Partial Data completes the step with whatever data the API returned and its errors beside it, so later steps can read both; the step still fails when the API returned no data at all.
Read Timeout (ms)	How long to wait for the API to answer.
Max Response Size (MB)	The largest response the step accepts. 1 MB when left unset. A larger response fails the step—select fewer fields to stay under it.
Dry Run: Outbound HTTP	Overrides the default policy for what this step actually sends during a dry run. Leave it unset to inherit that default.

Checked as you write

The note under Query checks the query against the API's schema as you type. It catches what the API would otherwise reject at run time:

• GraphQL that doesn't parse.
• A field, argument, or type the API doesn't have, with the line it is on—or a mutation, when the API has none.
• A variable used but not declared, or declared with the wrong type.
• A subscription, which the step can't run.

Up to five problems are listed at once. Below them, the note says whether a dry run sends the operation.

When the API's schema can't be read, only the syntax is checked. The connection's own note says why the schema is missing.

Exploring the API in GraphiQL

Click Open GraphiQL in the note under Query and GraphiQL opens over the form, loaded with the step's query and the API's schema. Use it to browse the API's documentation, build a query by ticking fields in the explorer, rely on autocompletion as you type, and run the query to see real results.

When the query is right, click Use This Query to put it back into the step's Query field. Closing GraphiQL instead leaves the field as it was.

GraphiQL keeps the variables you enter for each step, in your browser, so they're there the next time you open it from that step. They're test values only: what the step sends at run time comes from its Variables field.

Calls from GraphiQL go through the connection on the server, so the connection's credentials never reach your browser. Running a mutation asks you to confirm first, because it changes data on the API just as a live run would. Opening GraphiQL needs the Builder role.

note

GraphiQL writes back only the query. If the query holds several operations, choose which one the step runs under Operation Name.

Variables

Declare a variable in the query for each value that comes from an earlier step, and bind it under Variables rather than writing the value into the query:

1
query Country($code: ID!) {
2
  country(code: $code) {
3
    name
4
    capital
5
  }
6
}

Variables then lists the fields it expects—here code, with its type, marked required because the query declares it non-null with no default. Add a field for each variable, named without its $, and type its value or take it from an earlier step. A required field not yet added, or a name the query doesn't declare, is flagged.

Each value is checked against its variable's type: GraphQL's own scalars from the declaration alone, and enums and input objects from the API's schema. A text value bound to a number variable is converted when it holds a number, so "2" from an earlier step is sent as 2.

A run whose variables don't match what the query declares—a required one left empty, or "two" for an Int—fails before anything is sent, naming the variable at fault. A variable the query gives a default can be left empty, and the API applies the default.

To pass an object built by an earlier step as the whole set of variables, switch Variables from Object to Variable.

Writing the query with Esca

Esca can write the Query field for you, where a model is configured for the site. A hint appears over the field's label—click it, or place the cursor in the field and press Ctrl+Enter (Windows/Linux) / ⌘+Enter (Mac).

With the field empty, the starter is What can I query?, which surveys what the API offers and writes a query for the most useful part of it. Once the field holds a query, the starters are Explain, Use variables, which turns values written into the query into declared variables, and Tidy.

Esca writes against the API's schema and hands over only a query that validates against it. A field the API doesn't have is caught and corrected before the query reaches the field.

What a dry run sends

A dry run treats a query as read-only and a mutation as a write.

Policy	What leaves the system
None	Nothing. Every call is logged with its operation, and the step returns its test output instead of a real response.
Safe Methods Only	Queries are sent for real, so later steps see live data. Mutations are logged and skipped.
All Methods	Everything, mutations included. A dry run rehearses nothing about this step's calls under this policy—choose it only when the API is itself a test target.

With no policy set on the step and none set as the default, Safe Methods Only is what applies. Either way, the request is still prepared—the endpoint's address checked and the connection's credentials fetched—so a dry run catches a connection that would fail.

Output

Value	Description
Data	What the query returned, shaped by the fields it selects. The variable picker shows those fields by name, aliases included, so a later step can reference country.name directly.
Errors	The errors the API returned, each with its Message and Path. Empty unless Continue With Partial Data is chosen and the API returned errors beside its data.
Extensions	Anything the API returned under extensions, such as cost or tracing data.

Gotchas

• One call per step. GraphQL has no standard for pagination, so the step does not page through results. Ask for the page you need with the arguments the API offers, such as first and after.
• No subscriptions. A subscription needs a connection that stays open, which a step doesn't hold.
• No redirects. A redirect fails the step and names where it pointed, so you can put that URL in the connection.
• No local network addresses. As with the HTTP Request action, requests to loopback, link-local, private, and similar addresses are refused unless an administrator has allowed local network requests.