Stitching GraphQL APIs

Stitch multiple schemas together to expose one unified GraphQL server to your clients.

What is GraphQL stitching?

When you begin with a GraphQL schema, you might set up query resolution for a few API services. For example, you might start out with a GraphQL schema for a customer account information page. However, as your organization grows, you might have difficulty maintaining a single schema for your multiple APIs. For example, in a large organization, each team might develop their own APIs, increasing the number of APIs from dozens to hundreds. You might want to surface all of the APIs together, instead of forcing users to make GraphQL queries to individual APIs. For example, you might want to show the customer account information, billing information, and financial portfolios for a customer all on one page.

To call multiple GraphQL APIs together, you develop what is known as a stitched schema. In a stitched setup, you create individual subschema for microservices that can be managed independently. These subschema might be local GraphQL resolver services or APIs running on remote servers. Then, you combine multiple GraphQL APIs into one unified schema that can delegate parts of a request to the relevant subschema. The unified, or stitched, schema allows you to set up a single route through which users can reach all relevant information across your APIs.

Schema merging

Schema merging refers to the process of consolidating the subschema definitions and resolvers from your multiple API services into a single, stitched schema. In Gloo Gateway, you create a Gloo GraphQLStitchedSchema custom resource, which generates a stitched schema that incorporates all the types and fields from each subschema. When clients query the route for the stitched schema, Gloo Gateway creates requests to the individual services, and then stitches the responses back together into one response to the client.

On its own, schema merging does not handle situations in which your APIs might have overlapping types. If you do not have overlapping types, you can get started by following the schema merging guide. If you do have overlapping types, continue to type merging.

Type merging

When you merge your subschema into one stitched schema, you might have APIs that contain the same types as other APIs. For example, if you merge the subschema for the account information, billing information, and financial portfolio APIs, these might all contain a type called customer. However, each customer type might contain different fields than the other APIs’ customer types. To ensure that only one reconciled customer type exists for the stitched schema, and that it contains all the necessary fields across each subschema, you use type merging.

To enable type merging, you create a Gloo GraphQLStitchedSchema custom resource that references each GraphQL API subschema. Within the subschemas that contain a shared type, you specify the type name, and the set of partial fields that the subschema provides. Gloo Gateway uses this resource to generate a stitched schema, which incorporates all the partial types from each of the respective services. When clients query the route for the stitched schema, Gloo Gateway creates requests to the individual services, and then stitches the responses back together into one response to the client.

To get started, follow the type merging guide.