Catch the highlights of GraphQLConf 2023! Click for recordings. Or check out our recap blog post.
Docs
Source Handlers
GraphQL

GraphQL

image

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:

npm i @graphql-mesh/graphql

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

.meshrc.yaml
sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: http://my-service-url:3000/graphql
💡

You can check out our example that uses schema stitching with a PostgreSQL data source. Click here to open the example on GitHub.

Headers

Read about configuration and examples.

Fetching SDL or introspection from CDN or any other schema registry tool

Let's say the introspection disabled in your production environment of your GraphQL source, and you want to provide your SDL or introspection seperately;

.meshrc.yaml
sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: https://api.github.com/graphql
        # You can provide your SDL or introspection seperately
        source: https://docs.github.com/public/schema.docs.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}
        connectionParams:
          # Use the token from the HTTP header and pass it down to the WebSocket connection params
          token: Bearer {context.headers['x-my-api-token']}
          # You can also alter the existing incoming WebSocket connection params
          # token: Bearer {context.connectionParams.token}
          # Or use a static value from environment variables
          # token: Bearer {env.MY_API_TOKEN}

In this case, CLI's build command won't save the introspection in the artifacts, so your Mesh won't start if source URL is down.

Hive Integration

If you use GraphQL Hive to manage your GraphQL APIs as a schema registry, you can use the following configuration to fetch your schema from Hive:

.meshrc.yaml
sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: https://my-api.com/graphql
        source: https://cdn.graphql-hive.com/asce7c12-753d-hive-bee-d7f2c803e232/sdl?ext=.graphql
        schemaHeaders:
          X-Hive-CDN-Key: 'aabTxbEyC78NvSPQNO+qLrrRnBvODJJ8k4sL/2EtIwc='

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:

.meshrc.yaml
sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        source: ./my-local-schema.ts
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:

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.

.meshrc.yaml
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
timeout

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

.meshrc.yaml
sources:
  - name: uniswapv2
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
        timeout: 5000 # 5 seconds
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.

.meshrc.yaml
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
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.

.meshrc.yaml
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"

or

  • source (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.
IntroductionOpenAPI / Swagger