Tutorial: Schema Stitching in GraphQL from Scratch

One of the most powerful ways to use GraphQL is to combine two distinct GraphQL schemas, allowing us to create aggregate queries that can load data from multiple back-ends. This is called schema stitching.

Stitch together multiple data sources for more powerful GraphQL servers.

In this tutorial, we’ll learn how easy it is to stitch together two GraphQL data sources following the GrAMPS format.

GrAMPS is a small tool to make your GraphQL schema definitions reusable and shareable. When combined with schema stitching, developers can now publish a data source as an npm package, allowing us to combine and remix different data sources with no code duplication! 🎉

Make sure to check out the source on GitHub, try out the quickstart, and maybe even give the repo a star. ⭐️

Part 1: Create a Data Source

To get started, let’s create our first data source using the GraphQL CLI:

npx is one of my favorite tools of 2017.

In src/index.js, we can declare the entire data source for the sake of simplicity:

A simple GrAMPS data source.

This data source exposes two queries:

• getContext — returns an array of object keys that are present in the data source’s context object
• getById — exposes id and value fields

Let’s test this out by running the data source:

yarn dev

At http://localhost:8080/playground, run the following query:

We should see the following return value:

So far so good.

Add Local Schema Stitching

Next, let’s add some schema stitching to the existing data source, just to make sure it’s working the way we expected.

In src/index.js, add a stitching property with the following definitions:

The `typeDefs`, `context`, and `resolvers` fields have been omitted for brevity.

Restart the data source in your terminal (ctrl + C to stop, yarn dev to start), head to http://localhost:8080/playground, and run the following query:

We should see the following return value:

NOTE: Notice that the contexts are different in getStitchingContext. This happens because each data source scopes its context to its own namespace to prevent accidentally relying on another data source's context. However, schema stitching does rely on multiple data source's contexts, so we include all of the data sources' contexts.

Add a Second Data Source

Next, let’s create a second data source so we can set up more realistic schema stitching.

In your terminal, move into the same directory where your first data source was created, then run the following to create a second data source:

In src/index.js, create the second data source all in one place:

This data source is pretty bare bones: it has a single query — getSomeValues — that exposes three fields that have text and echo the val the query was called with.

To test it, let’s fire up the new data source along with the original data source:

yarn dev --data-source ../data-source-stitchingtest

NOTE: yarn dev is shorthand for gramps dev --data-source ., so what we're doing here is effectively running gramps dev --data-source . --data-source ../data-source-stitchingtest

Open http://localhost:8080/playground and update the query to call getSomeValues:

The output should be:

Use Schema Stitching to Combine the Two Data Sources

Finally, let’s add stitching config to tie the two data source together. In the second data source, add the following:

The `typeDefs`, `context`, and `resolvers` fields have been omitted for brevity.

First, we use linkTypeDefs to extend the STX_Test type by adding a new field called stitched.

Then, in resolvers, we set up stitched — which is a field on our first data source, remember — to get its value from the getSomeValues query, which is in the second data source.

Under the hood, this is done using mergeSchemas. Be sure to check that out for additional information about how schema stitching happens, and some of the different ways you can work with it.

With the stitching config in place, let’s fire it up and test it.

Run the following command to start a gateway with both data sources:

yarn dev --data-source ../data-source-stitchingtest

Then, open http://localhost:8080/playground and add the stitching field to the query:

Once executed, we’ll see the following:

And that’s it! We now have one data source including data from a second data source as part of its own queries.

For more information, see the GrAMPS data source docs.

Did you enjoy this post? Please consider clapping, sharing this article, or retweeting this tweet:

Thanks for reading!