If you'd told me eight months ago that I'd end up writing a book (opens in a new tab) on Schema Stitching, I wouldn't have believed it.
That's because eight months ago my team was trying to mature an old GraphQL prototype into a formal API product, and our dependence on Schema Stitching v4 (a famously abandoned project (opens in a new tab) of Apollo) imposed numerous bugs, limitations, and performance bottlenecks on our work. I researched transitioning to the newer Apollo Federation (opens in a new tab) as a solution to these woes, but the involved migration path proved too daunting for our immediate time constraints.
Not "The Old" Schema Stitching
Something remarkable happened at this critical juncture for my team...
GraphQL Tools (opens in a new tab) (the repo of Schema Stitching libraries) was brought back to life by The Guild and friends. The most pivotal new addition was a small mention of "type merging (opens in a new tab)", a feature that introduced automated query planning for types distributed across services (very similar to Apollo Federation). The new v5 library was still pretty raw, but it started a feedback loop that matured the library dramatically in v6, and then again in v7 (and will again in v8!).
During these development cycles, numerous missing Stitching features were identified and added: batch execution (opens in a new tab) for consolidating sub-service requests, computed fields (opens in a new tab) for encapsulating service concerns, interface proxies (opens in a new tab) for bridging interfaces across services, and schema directives (opens in a new tab) for configuring stitched schemas via SDL annotations. Also, the library documentation (opens in a new tab) was rewritten from top-to-bottom for a new generation of users.
Coming into 2021, Schema Stitching has been revitalized into an un-opinionated library capable of building an opinionated framework like Apollo Federation. If you want out-of-the-box workflows, Federation is the tool for you. Otherwise, Stitching is the comparable alternative that keeps you in control of your full system architecture.
The Handbook
The tricky thing about the self-service nature of Schema Stitching is that its usage extends beyond just the scope of library documentation. To bridge this knowledge gap, the Schema Stitching Handbook (opens in a new tab) was started as a companion guide that walks through building stitching libraries into practical applications. The content is split into a few major sections:
- Foundation chapters cover the setup and use of core stitching library features. These chapters provide code examples and detailed explanations of subjects covered in the official documentation (opens in a new tab).
- Architecture chapters explore larger structural concerns around testing (opens in a new tab), versioning (opens in a new tab), and releasing (opens in a new tab) stitched schemas. Stitching has no CLI or managed services (opens in a new tab), but you may find that these tools are not prohibitively difficult to self-service.
- Other Integration chapters explore how other tools (opens in a new tab) and programming languages (opens in a new tab) fit into a stitched schema. Stitching is perfectly compatible with any valid GraphQL resource, and we're excited to catalog that here.
The Handbook is versioned as a living repo to provide a comprehensive guide that may evolve with the library. We look to you, fellow developers, to contribute your own discoveries of how Schema Stitching integrates with tools and languages that we haven't explored yet.
A New Year
Whether you're planning a new API project, looking to migrate an existing one, or curious of alternatives for your current distributed GraphQL architecture, 2021 is the year to give Schema Stitching a fresh look. Read the new documentation (opens in a new tab), review the handbook (opens in a new tab), watch the video series (opens in a new tab), or join us for a conversation (opens in a new tab) to learn about the exciting progress that was made last year.