GraphQL Connector

Introduction

Using the Hasura GraphQL Connector, you can instantly bring an existing GraphQL API into a Hasura DDN supergraph API.

The GraphQL Connector replaces the Remote Schemas functionality from Hasura v2 and can also be used to bring in an existing Hasura v2 GraphQL API into Hasura DDN.

The connector translates the root-fields of a GraphQL schema to NDC functions and procedures. This results in your GraphQL root fields being exposed as commands in the supergraph. This simplifies implementation and acts as a proxy more than a model.

The recent support for field arguments and header forwarding on Hasura v3 engine allow the connector to represent the majority of queries and mutations.

The connector is built using the Rust Native Data Connector SDK and implements the Native Data Connector Spec.

Features

Below, you'll find a matrix of all supported features for the GraphQL connector:

Feature	Supported	Notes
Queries	✅	All features that v3 engine currently supports
Mutations	✅
Header Passthrough	✅	Entire headers can be forwarded
Subscriptions	❌
Unions	❌	Can be brought in via scalar types
Interfaces	❌
Relay API	❌
Directives	❌	@cached, Apollo directives

Getting started

To get started with the GraphQL Data Connector, you can follow the guide here.

Prerequisites

If you've never used Hasura DDN, we recommend that you first go through the getting started. 😊

Configuration Overview

The configuration comprises the following files:

• configuration.json - Main configuration file. This is where you'll set up the connection to your underlying endpoint.
• configuration.schema.json - JSON Schema for your main configuration file. Allows your IDE to validate your configuration file, enhancing your configuration experience.
• schema.graphql - Stored GraphQL introspection. This file should be mostly left alone.

Introspection connection & execution connection

You may wish to connect to different endpoints for introspection and query execution. This can be the case if, for example, you want to introspect a locally running copy of your graphql endpoint. Additionally, you may wish to set certain static headers for introspection only.

To that end, the configuration contains both an execution and introspection connection configuration.

Request header forwarding

You may wish to forward headers from the original request to the underlying connector. To achieve this, set the request.forwardHeaders property to a non-empty array of string values. Glob patterns are supported.

You will also have to modify your connector link to add the following argument preset section:

kind: DataConnectorLink
version: v1
definition:
  # add this section
  argumentPresets:
    - argument: _headers
      value:
        httpHeaders:
          # list desired headers to forward
          forward:
            - Cookie
            - Authorization
            - X-Hasura-Admin-Secret
          additional: {}

Note the _headers argument name. This argument must not conflict with any root field arguments in your target schema. If there is a conflict, you may change this name in both your connector link, and your connector's configuration.json file

tip

Changing this configuration will modify the exposed NDC schema, which you will need to update.

Only do this after making the connector link changes described above.

Response header forwarding

You may want to forward request headers back to the client, typically when using the Set-Cookie header. To achieve this, set the response.forwardHeaders property to a non-empty array of string values. Glob patterns are supported.

You will also have to modify your connector link to add the response header section:

kind: DataConnectorLink
version: v1
definition:
  # add this section
  responseHeaders:
    headersField: headers
    resultField: response
    # list desired headers to forward
    forwardHeaders:
      - Set-Cookie

tip

Changing this configuration will modify the exposed NDC schema, which you will need to update.

Only do this after making the connector link changes described above.

warning

Note that returning multiple headers with the same name is not supported. Only the last header of a given name will be returned.

This may be a problem when using the Set-Cookie header.

This limitation will be remedied in the future.

Resources

• GraphQL Connector GitHub Repo

Configuration Reference

Configuration Root

Key	Value	Required	Description
introspection	ConnectionConfiguration	true	Connection configuration to use for introspection
execution	ConnectionConfiguration	true	Connection configuration to use for execution
request	RequestConfiguration / null	false	Additional configuration for requests
response	ResponseConfiguration / null	false	Additional configuration for responses

ConnectionConfiguration

Key	Value	Required	Description
endpoint	EnvironmentValue	true	GraphQL Endpoint URL
headers	Headers	false	A map of static headers to include in all requests

Headers

Key	Value	Required	Description
<customKey>	EnvironmentValue	true	A header to include in requests

EnvironmentValue

Either a literal string or a reference to an environment variable

Must have exactly one of the following fields:

Key	Value	Required	Description
value	string	true	Literal string value
valueFromEnv	string	true	Name of an environment variable

RequestConfiguration

Key	Value	Required	Default	Description
forwardHeaders	[string]	true	[]	List of request header names. May be glob patterns
headersArgument	string / null	false	_headers	Name of headers argument. Must be changed if it conflicts with existing root field argument names. Should match connector-link configuration
headerTypeName	string / null	false	_HeaderMap	Name of headers type. Must be changed if it conflicts with other types in the target schema. Should match connector-link configuration

ResponseConfiguration

Key	Value	Required	Default	Description
forwardHeaders	[string]	true	[]	List of response header names. May be glob patterns
headersField	string / null	false	headers	Name of the headers field in the response object. Should match connector-link configuration
responseField	string / null	false	response	Name of the response field in the response object. Should match connector-link configuration
typeNamePrefix	string / null	false	_	Prefix for response type name generation. May need to be changed in case of conflicts
typeNameSuffix	string / null	false	Response	Suffix for response type name generation. May need to be changed in case of conflicts