How to use multiple GraphQL endpoints with Urql

If you are familiar with GraphQL you should already have the need to query third party services data in parallel of your main GraphQL API. In this post I summary how I manage to handle multiple GraphQL API endpoints with a single Urql client.

Introduction

Recently, I had to migrate my Apollo Client stack to another GraphQL library. In facts, the way the library was handling tree parsing and request discovery was the source of performances issues viewable on the Google lighthouse scores, preventing the proper indexing on Google SERP. The library is heavy, and has too many tools that I don't use.

As a replacement, I opted for Urql. This library is 1) based on observables, 2) very light, 3) providing such an opposite approach of the Apollo's one: instead of an "all in one" tool ready for any kind of use case I would have, I compose myself my bunch of tools with additional modules to fit my needs. This approach leaves me with the ability to finely control what is bundled.

One of the features of Apollo Client that I really like is the

Link

HttpLink

So, if you want to know if it is possible to manage multiple GraphQL API with Urql and how to do it, you have found the right post.

Requirements: install required packages

Urql is a GraphQL client based on a collection of blocks that connect to each other. As I presented in the introduction, this is what allows us to compose the exhaustive list of tools we will use. Think of these modules as operators in the world of observables. And good news, this is exactly on what the library is built.

These blocks, called

exchanges

The order is important and must be logical according to the transformations you want to apply. According to the official documentation, you should always start with synchronous tasks and end with asynchronous ones.

When you configure an Urql client, you have access, by default, to certain exchanges:

• dedupExchange

  : ensures that identical queries are not executed twice

• cacheExchange

  - cache the result of the requests

• fetchExchange

  : takes care of executing the HTTP request (using the

  fetch

  API)

For our problem, we will need an

exchange

authExchange

Basically, it allows us to easily configure an authorization system (for example via JWT), but it will mainly be used to change the context of our request on the fly.

Let's start by installing:

# With Yarn
$ yarn add @urql/exchange-auth

# With NPM
$ npm install @urql/exchange-auth

Then we import it:

import { authExchange } from '@urql/exchange-auth

Creating the GraphQL client

This function should return the Urql client creation method with the correct configuration parameters and the different exchanges you wish to implement:

import { Client, createClient } from 'urql'

export function createGraphqlClient(): Client {
  return createClient({
	url: 'your-api-url', // The default client url
	fetchOptions: {
	  credentials: 'same-origin',
	  method: 'GET',
	  headers: {
	    Authorization: `Bearer ...`,
	    'Content-Type': 'application/json',
	  }
	},
	preferGetMethod: true,
	exchanges: [],
  })
}

Then we just need to add "basic" exchanges (read more):

import { ..., dedupExchange, cacheExchange, fetchExchange } from 'urql'

export function createGraphqlClient(): Client {
  return createClient({
		//...
		exchanges: [
			dedupExchange,
			cacheExchange,
			fetchExchange
		],
  })
}

Add authorization exchange

Once the client is configured with the basic options, we can add

authExchange

The overall idea is to copy the way we would use with Apollo Client (using

Link

To summarize, we will add to the context of each request an optional

clientName

The

authExchange

addAuthToOperation

getAuth

About

addAuthToOperation

addAuthToOperation({ operation }) {
  // if clientName is not setted in context, we return the current operation
  if (!operation.context.clientName) {
    return operation
  }
		
  const { clientName, fetchOptions } = operation.context
  const options = typeof fetchOptions === 'function' ? fetchOptions() : fetchOptions ?? {}
		
  switch (clientName) {
    case 'endpoint-a': {
      const headers = {
        ...options.headers,
        Authorization: `Bearer ...`,
      }
		
      const context = {
        ...operation.context,
        url: 'endpoint-a-url',
        fetchOptions: {
          ...options,
          headers,
        }
      }
		
      return makeOperation(operation.kind, operation, context)
    }
    case 'endpoint-b': {
      const headers = {
        ...options.headers,
        Authorization: `Bearer ...`,
      }
		
      const context = {
        ...operation.context,
        url: 'endpoint-b-url',
        fetchOptions: {
          ...options,
          headers,
        }
      }
		
      return makeOperation(operation.kind, operation, context)
    }
    default: {
      throw new Error(`Unexpected object: ${clientName}`)
      return operation
    }
  }
}

Add as many cases as data sources needed.

For

getAuth

getAuth: null

If needed, you can add logic, like retrieving a token with a promise for example:

getAuth: async () => {
  const token = await getToken()

  return { token }
},
addAuthToOperation({ authState, operation }) {
  const token = authState.token
  // ...
}

Request example with GraphQL client

To use the correct API with the GraphQL client:

function getDataFromEndpointA() {
  const { data } = await client.query(myQueryForEndpointA, {}, {
    clientName: 'endpoint-a',
  }).toPromise()

  return data
}

function getDataFromEndpointB() {
  const { data } = await client.query(myQueryForEndpointB, {}, {
		clientName: 'endpoint-b',
  }).toPromise()

  return data
}

Request example with React hooks

To use the right source through an Urql client integration with React hooks:

const [{ error, data, fetching }] = useQuery(
  myQueryForEndpointA,
  {} // this object contains GraphQL request variables,
  context: useMemo(() => ({
    clientName: 'endpoint-a'
  }), []),
})

const [{ error, data, fetching }] = useQuery(
  myQueryForEndpointB,
  {} // this object contains GraphQL request variables,
  context: useMemo(() => ({
	  clientName: 'endpoint-b'
  }), []),
})

Note: remember to use

useMemo

Conclusion

You should now have enough information to set up an Urql client that handles multiple GraphQL API endpoints.

Notes:

• the current code is not 100% type safe since the

  clientName

  key does not exist in the Typescript typing of the Urql context,

• adding a data source increases the complexity in your typing management if you use

  graphql-codegen

  . We'll talk about that in a future post.

Just for you I created a Gist to summarize all the code snippets I wrote on this post. Do not hesitate to add a comment or to give your feedback on it.

And if you have any questions (or if you wanna talk) you can contact me on Twitter.