Adding a remote schema¶

Introduction¶

Follow the steps below to add a remote schema to the Hasura GraphQL engine.

Step 1: Write a custom GraphQL server¶

You need to create a custom GraphQL server with a schema and corresponding resolvers that solve your use case (if you already have a functional GraphQL server that meets your requirements, you can skip this step).

You can use any language/framework of your choice to author this server and deploy it anywhere. A great way to get started is to use one of our boilerplates:

• Boilerplates

Step 2: Merge remote schema¶

To merge your remote schema with the GraphQL engine’s auto-generated schema:

Console

CLI

API

Head to the Remote Schemas tab of the console and click on the Add button on the left sidebar.

You need to enter the following information:

• Remote Schema name: an alias for the remote schema that must be unique on an instance of the GraphQL engine.
• GraphQL server URL: the endpoint at which your remote GraphQL server is available. This value can be entered manually or by specifying an environment variable that contains this information.

To add a remote schema, edit the remote_schemas.yaml file in the metadata directory as in this example:

- name: my-remote-schema
  definition:
    url: https://graphql-pokemon.now.sh/
    timeout_seconds: 60
    forward_client_headers: true

Apply the metadata by running:

hasura metadata apply

You can add a remote schema by using the add_remote_schema metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "add_remote_schema",
    "args": {
        "name": "my-remote-schema",
        "definition": {
            "url": "https://graphql-pokemon.now.sh/",
            "forward_client_headers": true,
            "timeout_seconds": 60
        }
    }
}

• Headers: configure the headers to be sent to your custom GraphQL server:

  • Toggle forwarding all headers sent by the client (when making a GraphQL query) to your remote GraphQL server.

  • Send additional headers to your remote server - these can be static header name-value pairs; and/or pairs of “header name-environment variable name”. You can specify the value of the header to be picked up from the environment variable.

    Example: Let’s say your remote GraphQL server needs a X-Api-Key as a header. As this value contains sensitive data (like API key in this example), you can configure the name of an environment variable which will hold the value. This environment variable needs to be present when you start the GraphQL engine. When Hasura sends requests to your remote server, it will pick up the value from this environment variable.

Click on the Add Remote Schema button to merge the remote schema.

Step 3: Make queries to the remote server from Hasura¶

Points to remember¶