Schema stitching in GraphQL: everything you need to know

Are you ready to get to grips with GraphQL schema stitching? Whether you’re after an introduction to schema stitching, wondering about the finer points of schema stitching vs federation or trying to find out which GraphQL tools schema stitching is easiest with, we’ve got you covered.

Benefits of GraphQL

GraphQL took the industry by storm as a query language for APIs with its complete and understandable API data descriptions. It empowered clients to ask for just what they needed and nothing more, with a schema describing the shape of the available data.

Now, schema stitching means you can combine multiple schemas into a single endpoint.

What is schema stitching?

Schema stitching in GraphQL enables a single query to span multiple GraphQL schemas. This can enhance performance by reducing the need for multiple roundtrips. It also has benefits in developer experience (DX) terms. After all, who wants to maintain and interact with more APIs than is absolutely necessary?

The need for schema stitching in GraphQL

GraphQL stitching comes into its own when combining smaller services to deliver a larger system offering. Clients can make a single call, with the gateway putting in the legwork and returning a response containing data gathered from multiple subschemas. This is particularly useful when your underlying services aren’t all GraphQL.

There’s a win for developer efficiency here – each team can maintain its schema(s) based on its area of work and expertise. With an API gateway providing a uniform frontend irrespective of what’s happening behind the scenes, efficiency is delivered at the client level and across dev teams.

Schema stitching benefits for backend development

Using GraphQL schema stitching delivers a range of benefits for backend development:

  • Flexibility for different teams to maintain different subschemas.
  • Modularity that encourages code reusability and simplifies collaboration within and between teams.
  • Scalability, as different parts of the GraphQL API can scale at different speeds and respond flexibly to changes in need (for example, if one part of your application experiences higher traffic than others).
  • Efficiency, for example by enabling seamless integration of legacy systems and data sources using different architectural constraints, without you having to rewrite the backend completely.
  • Optimised performance, as schema stitching can reduce the need for multiple API calls.

Benefits for frontend development

Frontend developers can enjoy some schema stitching-related wins too:

  • The unified GraphQL schema abstracts away the complexities of dealing with a mishmash of data sources and/or microservices, making the API easier to understand and consume. This reduces the learning curve for new team members.
  • A stitched schema’s consistent data structure can deliver standardisation and predictability in terms of data structure. This means that frontend developers can query and manipulate data efficiently without stressing about adapting to numerous data formats from multiple APIs.
  • Increased data fetching and performance efficiency can bring more data in fewer requests, with the associated latency reduction improving the user experience.
  • Easier testing and mocking, , with frontend developers able to create mock versions of the backend API to test frontend components independently.
  • Easier third-party API integration, with a unified and consistent interface across different data sources reducing the complexity of handling multiple external APIs.

There is also more scope for independence between backend and frontend teams with GraphQL schema stitching. The ability to make changes in the backend and tinker without impacting the exposed schema means that frontend developers can be confident that everything will continue functioning correctly even as adjustments are made. This includes handling versioning and deprecation smoothly, ensuring that the schema can evolve.

How schema stitching works: the process of schema stitching

Schema stitching in GraphQL combines multiple schemas into a single endpoint, neatly creating a unified GraphQL schema. Introspection ensures that requests can be delegated to the appropriate subschema. It explores the schema structure and directs requests accordingly.

At the other end of the process, after handling type name collisions and associating and adding fields and types, GraphQL stitching enables data from different subschemas to be resolved into a single response.

Understanding GraphQL schema stitching vs federation

You can use stitching and federation to deliver multiple services through a single endpoint.

  • With stitching, you must define the stitching yourself in the gateway. This is great if you have a gateway that connects to underlying services that are not GraphQL – for example, if you have a gateway connected to a REST API.
  • With federation (which you can only use for GraphQL services), you tell the gateway where to look for different objects and which URLs they live at. Then the gateway stitches everything together automatically, using subgraph metadata. The key benefits are lower maintenance and greater flexibility.

Schema stitching versus merging

GraphQL schema merging is not the same as schema stitching:

  • Stitching builds a proxy schema over the top of the subschema APIs to create a unified endpoint.
  • Merging creates a single executable schema by consolidating type definitions and resolvers from local schema instances.

Merging can create some issues to look out for, particularly in relation to GraphQL federation:

  • Subgraphs with the same name for shared types (objects, inputs, enums, etc.) may cause errors when schemas merge into a federated supergraph.
  • Schema merging can fail, depending on the order of resolving subgraph schemas, if individual subgraphs aren’t normalised before attempting a merge.

The key to success is choosing the right GraphQL tools for stitching, merging, federation and more.

Want more input? Learn what API management is, then dive into our API strategy articles to take your knowledge – and your business – to the next level.