GraphQL

This handler allows you to load remote GraphQL schemas and compose them into a supergraph.

How to use?

If you want to load a remote GraphQL subgraph by introspecting the endpoint, you can only provide endpoint in the configuration like below;

mesh-config.ts

import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Users', {
        endpoint: 'http://localhost:4001/users'
      })
    }
  ]
})

Load the schema via URL or local file (Hive CDN etc)

If you want to load a remote GraphQL subgraph from a CDN, you can provide source in the configuration like below;

In this case, Mesh will take the schema from source, but execute the operations against the endpoint.

mesh-config.ts

import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('GitHub', {
        endpoint: 'https://api.github.com/graphql',
        // You can provide your SDL or introspection seperately
        source: 'https://docs.github.com/public/schema.docs.graphql',
 
        operationHeaders: {
          // This forwards the header from the incoming request to the remote server
          authorization: 'Bearer {context.headers["x-my-api-token"]}'
        }
      })
    }
  ]
})

Headers

Read about configuration and examples

Fetch Strategies and Multiple HTTP endpoints for the same source

If you want to have an advanced fetch strategy for the GraphQL source such as retrying twice or timeout in 30 seconds etc. Also, you can have different HTTP endpoints for a single source, and you can configure Mesh to get a better execution flow.

For example, you can make a request to both endpoints and return the fastest response with race strategy.

All fetch strategies can be combined to create the ultimate execution flow:

retry

The retry mechanism allow you to specify the retry attempts for a single GraphQL endpoint/source.

The retry flow will execute in both conditions: a network error, or due to a runtime error.

mesh-config.ts

import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Uniswap', {
        endpoint: 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2',
        // Specify here, if you have an unstable/error prone indexer
        retry: 2
      })
    }
  ]
})

timeout

The timeout mechanism allow you to specify the timeout for a given GraphQL endpoint.

mesh-config.ts

import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Uniswap', {
        endpoint: 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2',
        // 5 Seconds
        timeout: 5_000
      })
    }
  ]
})

fallback

The fallback mechanism allow you to specify use more than one GraphQL endpoint, for the same source.

This is helpful if you have a fallback endpoint for the same GraphQL API.

mesh-config.ts

import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Uniswap', {
        strategy: 'fallback',
        sources: [
          {
            endpoint: 'https://bad-uniswap-v2-api.com',
            retry: 2,
            timeout: 5_000
          },
          {
            endpoint: 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2'
          }
        ]
      })
    }
  ]
})

race

The race mechanism allow you to specify use more than one GraphQL endpoint, for the same source, and race on every execution.

If you have different places that service is deployed, this is useful to get the fastest response by racing them.

mesh-config.ts

import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Uniswap', {
        strategy: 'race',
        sources: [
          {
            endpoint: 'https://bad-uniswap-v2-api.com'
          },
          {
            endpoint: 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2'
          }
        ]
      })
    }
  ]
})

Introduction OpenAPI