chesterdocs

#Connect a GraphQL API

A GraphQL adapter sends every action as a POST to one endpoint path; its actions are queries and mutations, imported by introspection or written by hand, and any GraphQL error fails the call.

#How a call is put together

sequenceDiagram
  participant P as Service task
  participant C as Chester
  participant G as GraphQL API
  P->>C: Action "customer" with variables
  C->>G: POST environment host + GraphQL path<br/>{ query, variables }
  G-->>C: { data, errors }
  alt errors is not empty
    C-->>P: The call failed — retried
  else
    C-->>P: data, under the task's id
  end

#Create a GraphQL adapter

  1. Open the system, click Add adapter and choose GraphQL.

  2. Give it an Adapter name and a GraphQL path, such as /graphql. The host comes from the environment.

  3. Optionally Import GraphQL schema:

    • Introspection — enter the endpoint's URL; your browser asks it for its schema;
    • Datei hochladen (upload a file) — an introspection result as JSON.

    Every query and mutation becomes an action, with a generated query text and its arguments.

  4. Click Create adapter.

⚠️ Introspection runs from your browser, without a login. An API that needs one, or that does not allow calls from the browser, cannot be introspected this way — export its schema as JSON and upload it.

⚠️ A schema file in GraphQL's own notation (.graphql) cannot be read; only the JSON result of an introspection.

⚠️ A generated query for a field that returns a plain value — Boolean, a number, an enum — asks for a sub-field and is invalid. Correct it on the action.

#Write an action

On the action, set the operation type — query or mutation — the operation name and the query text, with its variables as $name. For an imported action, the step's Request body fills the variables. See Define a GraphQL action.

❌ Subscriptions are not supported.

#Configure it

The Configuration tab shows the same sections as an HTTP adapter. For GraphQL, only the GraphQL path and the Timeout have an effect:

  • ⚠️ Default headers, CSRF-Token, Allow self-signed TLS and the adapter's Transformations are not used for GraphQL calls. Transformations on the action are.
  • The timeout limits both how long Chester waits and the call itself.

#Logging in

The credential comes from the environment or the step, as for HTTP.

⚠️ An API Key credential is sent as the raw Authorization header.

⚠️ If renewing an OAuth2 token fails, the call is still made, with the old token.

#When the answer has errors

A response whose errors list is not empty counts as a failure — also when the status is 200 and some data came back. That data is thrown away, and the call is retried like any failed service call. See Call a system with a service task.