GraphQL

This handler allows you to load remote GraphQL schemas and use them with schema-stitching based on graphql-tools.

To get started, install the handler library:

yarn add @graphql-mesh/graphql

Now, you can use it directly in your Mesh config file:

sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: http://my-service-url:3000/graphql

Dynamic Header Values (e.g., for Authorization)

Mesh can take dynamic values from the GraphQL Context or the environmental variables. For example, if you use mesh dev or mesh start, GraphQL Context will be the incoming HTTP request.

The expression inside dynamic values should be as in JS.

From Context (HTTP Header for mesh dev or mesh start)

sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: http://my-service-url:3000/graphql
        operationHeaders:
          # Please do not use capital letters while getting the headers
          # Use "{context.headers['x-my-api-token']}" if you want just the value of the header
          Authorization: Bearer {context.headers['x-my-api-token']}
          # You can also access to the cookies like below;
          # Authorization: Bearer {context.cookies.myApiToken}

And for mesh dev or mesh start, you can pass the value using x-my-graphql-api-token HTTP header.

From Environment Variables

MY_API_TOKEN is the name of the environment variable you have the value.

sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: http://my-service-url:3000/graphql
        operationHeaders:
          Authorization: Bearer {env.MY_API_TOKEN}

Local Schemas

We recommend providing local schema by using the additionalTypeDefs and additionalResolvers configuration options.

However, it is also possible to use a local GraphQL Schema instance as a GraphQL Mesh source, as showcased below:

sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        schema: ./my-local-schema.ts

import { makeExecutableSchema } from '@graphql-tools/schema'
export default makeExecutableSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      foo: String
    }
  `,
  resolvers: {
    Query: {
      foo: () => 'FOO'
    }
  }
})

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:

sources:
  - name: uniswapv2
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
        retry: 2 # specify here, if you have an unstable/error prone indexer

sources:
  - name: uniswapv2
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
        timeout: 5000 # 5 seconds

sources:
  - name: uniswapv2
    handler:
      graphql:
        strategy: fallback
        sources:
          - endpoint: https://bad-uniswap-v2-api.com
            retry: 2
            timeout: 5000
          - endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2

sources:
  - name: uniswapv2
    handler:
      graphql:
        strategy: race
        sources:
          - endpoint: https://bad-uniswap-v2-api.com
          - endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2

Config API Reference

• endpoint (type: String, required) - A url or file path to your remote GraphQL endpoint. If you provide a path to a code file(js or ts), other options will be ignored and the schema exported from the file will be used directly.
• schemaHeaders (type: Any) - JSON object representing the Headers to add to the runtime of the API calls only for schema introspection
• operationHeaders (type: JSON) - JSON object representing the Headers to add to the runtime of the API calls only for operation during runtime
• useGETForQueries (type: Boolean) - Use HTTP GET for Query operations
• method (type: String (GET | POST)) - HTTP method used for GraphQL operations
• credentials (type: String (omit | include)) - Request Credentials if your environment supports it. See more

@default "same-origin"

• webSocketImpl (type: String) - Path to a custom W3 Compatible WebSocket Implementation
• introspection (type: String) - Path to the introspection You can separately give schema introspection
• subscriptionsProtocol (type: String (SSE | WS | LEGACY_WS)) - SSE - Server Sent Events WS - New graphql-ws LEGACY_WS - Legacy subscriptions-transport-ws
• retry (type: Int) - Retry attempts if fails
• timeout (type: Int) - Timeout in milliseconds
• batch (type: Boolean) - Enable/Disable automatic query batching

or

• schema (type: Any, required) - A file path to your GraphQL Schema If you provide a path to a code file(js or ts), other options will be ignored and the schema exported from the file will be used directly.