Documentation
Configuration
Sources
GraphQL Source

GraphQL Source

An upstream based on a simple, single GraphQL endpoint.

By using this source, you can easily wrap an existing GraphQL upstream server, and enrich it with features and plugins.

Schema Awareness

This source supports schema_awareness configuration. With schema awareness, the gateway will load the upstream GraphQL schema and use that information during plugins execution.

Plugins can access the schema and provide meaningful features, such as running GraphQL validation as part of the gateway.

Note: Schema Awareness is optional for the graphql source. When it’s not specified, the gateway will act as a simple proxy, without any knowledge of the upstream schema. Plugins that rely on the schema will emit a warning and will be skipped.

Configuration

Examples

YAML

config:
  endpoint: "https://my-source.com/graphql"
  schema_awareness: null
id: "my-source"
type: "graphql"

JSON

{
  "config": {
    "endpoint": "https://my-source.com/graphql",
    "schema_awareness": null
  },
  "id": "my-source",
  "type": "graphql"
}

Reference

endpoint
string
required

The HTTP(S) endpoint URL for the GraphQL source.

schema_awareness
optional

Schema Awareness configuration for the source. Enabling this configuration will configure the gateway to load the upstream GraphQL schema and use that information in other plugins.

When this configuration is not specified, Schema Awareness is disabled, and plugins will not have access to the upstream schema. In that case, the gateway will act as a simple proxy, without any knowledge of the upstream schema.

format
required

The expected format of the response/file.

The following options are valid for this field:
introspection

The schema awareness is provided as a GraphQL introspection response.

Please note that GraphQL introspection does not contain information about GraphQL directives usage, so it’s not suitable for runtimes/plugins that rely on directives.

sdl

The schema awareness is provided as a GraphQL SDL schema.

source
required

The source of the schema awareness. Can be either a local file, an inline string (hardcoded or from environment variables), or a remote endpoint.

The following options are valid for this field:
file

Loads schema awareness from a local file.

type
literal: file
required

To use this variation, please specify the type: file in your configuration.

path
string
required
inline

Loads schema awareness from an inline string. You can also use environment variable intropolation in this field.

type
literal: inline
required

To use this variation, please specify the type: inline in your configuration.

content
string
required
remote

Loads schema awareness from a remote endpoint.

type
literal: remote
required

To use this variation, please specify the type: remote in your configuration.

url
string
required

Endpoint to load the schema awareness from.

headers
object
default: {}

Optional headers to include in the request (for example: authentication).

By default, when format: introspection is used, the gateway will add Content-Type: application/json and Accept: application/json to the request headers.

method
string
default: "GET"

HTTP method to use when fetching the schema awareness from the remote endpoint.

By default, this field is set to GET. If you are using format: introspection, you should change this property to be POST.

polling_interval
string
optional
default: "1m"

Polling interval for reloading the schema awareness.

This field is ignored on WASM runtime.

on_error
default: "terminate"

What to do in case of a failure to load the schema awareness.

The following options are valid for this field:
terminate

On binary runtime, this configuration will stop the gateway with an error.

On WASM runtime, this field will return 500 in case of a failure to load.

ignore

Ignores the failure and report it to the log, without stopping the gateway or interrupting the execution.

GeneralFederation Source