GraphQL Request v2

The GraphQL Request Node executes GraphQL queries and mutations against a GraphQL endpoint that you configure on the Connection. GraphQL is an API query language that exposes typed schemas for reading and changing application data through a single endpoint.

The Node supports Basic, Bearer, and several OAuth authentication modes, validates each request against the endpoint's schema, and generates schema-driven templates through introspection.

Revision History

0.0.1.2 - Initial release.
0.0.1.6 - Added OAuth authorization-code authentication.
0.0.1.7 - Preserved complete GraphQL endpoint URLs, including paths and ports.
0.0.1.9 - Added the OAuthClientCredentials, OAuthPasswordCredentials, and OAuthAuthorizationCodeWithPkce authorization modes with independent Connection settings, and renamed the existing OAuth mode to OAuthAuthorizationCode.

Connection

The Connection stores the GraphQL endpoint, authentication settings, metadata used for templates, and the query used for connection testing. Each OAuth authorization mode keeps its own set of OAuth properties, so the values you enter for one mode are not shared with another.

Property Type Description
Url String Absolute HTTP or HTTPS URL of the GraphQL endpoint. The complete path and port are retained.
Authorization Enum Authentication mode: None, Basic, Bearer, OAuthClientCredentials, OAuthPasswordCredentials, OAuthAuthorizationCode, or OAuthAuthorizationCodeWithPkce.
Username String Username used when Authorization is Basic.
Password Masked Password used when Authorization is Basic.
BearerToken Masked Token used when Authorization is Bearer.
AuthUrl String OAuth authorization endpoint used when Authorization is OAuthAuthorizationCode or OAuthAuthorizationCodeWithPkce.
TokenUrl String OAuth token endpoint used by every OAuth authorization mode.
ClientId Masked OAuth client identifier used by every OAuth authorization mode.
SecretKey Masked OAuth client secret used by every OAuth authorization mode.
Scope String OAuth scopes requested during authentication.
OAuthUsername String Resource-owner username used when Authorization is OAuthPasswordCredentials.
OAuthPassword Masked Resource-owner password used when Authorization is OAuthPasswordCredentials.
AccessToken Masked OAuth access token populated after you connect the account or after the Node obtains a token.
RefreshToken Masked OAuth refresh token populated when the provider returns one.
CustomHeaders String Additional headers in Key: Value format, one per line.
AuthenticationTestPath String Shared HTTP test property included on the Connection. The GraphQL Connection test uses Authentication Test Query instead.
AuthenticationTestHttpMethod Enum Shared HTTP test property included on the Connection. The GraphQL Connection test uses Authentication Test Query instead.
Authentication Test Query String Lightweight GraphQL query executed by the Connection test action.
Schema String Hidden cached introspection schema populated by the Acquire Metadata Connection action.
Maximum Object Depth Integer Depth limit used when building sample templates from the schema. The default is 5.

Setup Notes

  • Obtain the GraphQL endpoint URL and confirm that schema introspection is available.
  • Enter the complete absolute HTTP or HTTPS endpoint in Url, including any required path and explicit port.
  • Choose an authentication mode supported by the endpoint.
  • When you use OAuthClientCredentials, provide TokenUrl, ClientId, SecretKey, and any required Scope. The Node obtains an access token from the token endpoint when it needs one.
  • When you use OAuthPasswordCredentials, provide the same properties together with OAuthUsername and OAuthPassword. The Node obtains tokens with the resource-owner credentials when it needs them.
  • When you use OAuthAuthorizationCode or OAuthAuthorizationCodeWithPkce, provide AuthUrl, TokenUrl, ClientId, SecretKey, and any required Scope, then complete the account authorization step so the Connection can store AccessToken and RefreshToken. OAuthAuthorizationCodeWithPkce also protects the browser redirect with S256 PKCE.
  • Add any required custom headers to CustomHeaders in Key: Value format, one per line.
  • Do not include an Authorization header in CustomHeaders when Authorization is set to any mode other than None.
  • Provide an Authentication Test Query that can run safely during connection testing. The test fails if the query returns GraphQL errors.
  • Click Acquire Metadata on the Connection to run the standard GraphQL introspection query and cache the schema used for templates.
  • Increase Maximum Object Depth when the generated templates are too shallow for your schema.

Methods

The Node exposes one method for queries and one for mutations. Both methods validate the GraphQL document against the cached schema before sending the request.

Query

Executes a GraphQL query document.

Parameter Type Description
Connection Connection Connection containing the endpoint, authentication settings, and cached schema.
Query String GraphQL query document to execute.
Body Array Optional stream of variable objects. If omitted, the query runs once with no variables.
Return Type Description
Response Array GraphQL response objects emitted for the executions.

Mutation

Executes a GraphQL mutation document.

Parameter Type Description
Connection Connection Connection containing the endpoint, authentication settings, and cached schema.
Query String GraphQL mutation document to execute.
Body Array Optional stream of variable objects. If omitted, the mutation runs once with no variables.
Return Type Description
Response Array GraphQL response objects emitted for the executions.

Usage Notes

  • Refresh the cached Schema whenever the upstream GraphQL contract changes, otherwise validation and templates may drift from the live endpoint.
  • If the Body stream contains multiple items, the Node executes the same query or mutation once per item.
  • If the Body stream is empty, the Node still executes once with no variables.
  • GraphQL application errors are returned in the errors array of the Response object. Transport and authentication failures still raise errors.
  • When an OAuth mode is selected and the endpoint returns HTTP 401, the Node renews the access token and retries the request once.

Known Issues

  • Introspection must be enabled on the endpoint to acquire metadata and generate templates.
  • Every OAuth mode requires a client secret, so PKCE-only public clients without a client secret are not supported.