Open Source composition and validation library for Apollo Federation
The Guild is proud to unveil its latest contribution to the GraphQL community: an MIT-licensed
drop-in replacement for @apollo/composition library.
We recognized the importance of the existing ecosystem of tools and existing knowledge base. That is
why @theguild/federation-composition library shares the same API, produces the exact same
supergraph SDL, and has an identical set of validation rules (including error messages and codes).
What Is Composition and Validation?
Apollo Federation is an architectural approach for building and managing GraphQL APIs at scale. It consists of several key components:
- Subgraphs: These are individual GraphQL services that represent specific domains or capabilities. Each subgraph serves a portion of the overall data and functionality that the API provides.
- Supergraph: The supergraph is the unified GraphQL schema that contains all the subgraphs. It’s essentially the merged view of all the individual subgraphs, creating a single API.
- Schema registry: This is a central repository that stores the schemas of the subgraphs. It’s where the gateway retrieves information about the available subgraphs and their schemas.
- Gateway: The gateway is responsible for handling incoming GraphQL requests from clients. It requires a supergraph to know how to route these requests across the appropriate subgraphs. The gateway retrieves this supergraph from the Schema Registry.
- Validation and composition: The process of composing the supergraph involves merging the schemas of the individual subgraphs. During this step, the system also checks for any potential errors that might arise from the composition. This is crucial to ensure that the resulting supergraph is both correct and compatible.
As you can see, the “Validation and Composition” step is critical to ensure reliability and integrity of the API within the schema registry.
Why Did We Create an Open Source Alternative?
The restrictions enforced by Elastic License 2.0 blocks vendors interested in offering a schema
registry as a service to use the @apollo/composition library. This library is crucial for
composing and validating federated subgraphs, as it’s the only available solution.
This situation creates a monopoly that prevents or at least slows down innovation in this space.
We wanted to change that and introduced alternatives:
- GraphQL Hive - replacement for Apollo Studio
@theguild/federation-composition- Open source alternative to@apollo/composition
In parallel to this, we’re working together with ChilliCream on an Open source alternative for Apollo Federation, called GraphQL Fusion.
You can watch a talk from GraphQLConf 2023 about GraphQL Fustion here.
A Familiar API
One of the core features of our open source replacement is its seamless compatibility with the
@apollo/composition API. This means that transitioning to our solution is not only effortless but
also ensures that developers can continue working with the familiar interface they’ve come to rely
on.
- import { composeServices } from '@apollo/composition';
+ import { composeServices } from '@theguild/federation-composition';
import { services } from './services';
const compositionResult = composeServices(services);Identical Validation and Composition Rules
Our composition library maintains absolute fidelity to the original library. It has the same set of validation rules and provides identical error messages. This ensures that existing projects and workflows remain uninterrupted, while still benefiting from the dramatic performance enhancements and no vendor locking.
Maintaining consistent validation rules, error codes, and error messages with the
@apollo/composition library is crucial as it streamlines the process of troubleshooting
composition errors using the official Apollo Federation documentation, GitHub issues, and
StackOverflow questions.
- import { composeServices } from '@apollo/composition';
+ import { composeServices } from '@theguild/federation-composition';
import { services } from './services';
const compositionResult = composeServices(services);
console.log(compositionResult);
// Outputs
{
"errors": [{
"message": "
[users] On field "User.profile", for @provides(fields: "name"): field "Profile.name" should not be part of a @provides since it is already provided by this subgraph (it is not marked @external)",
"extensions": {
"code": "PROVIDES_FIELDS_MISSING_EXTERNAL"
}
}]
}Because both libraries yields the same error code and message, you can look up
PROVIDES_FIELDS_MISSING_EXTERNAL on the
Apollo Federation error documentation or ask
other Apollo Federation users for help.
Identical Supergraph SDL
Our composition library is capable of producing supergraph SDL. This means that it can seamlessly integrate with Apollo Router, Apollo Server, Apollo Gateway and any other tool that supports supergraph SDL.
It allows other vendors to introduce new schema registries, GraphQL Hive is a good example of that.
20x Times Faster
In head-to-head comparisons, our implementation outperforms the original by a significant margin. When working with simple schemas, our solution is a staggering 5 times faster.
However, when it comes to large-scale graphs, the difference is even more pronounced, with our implementation boasting an astounding 20 times speed improvement (231ms instead of 4.48s).
cpu: Apple M1 Max
runtime: node v20.8.0 (arm64-darwin)
benchmark time (avg) (min … max) p75 p99 p995
------------------------------------------------- -----------------------------
• small supergraph (4 subgraphs)
------------------------------------------------- -----------------------------
apollo 4.05 ms/iter (2.98 ms … 9.33 ms) 4.38 ms 7.85 ms 9.33 ms
guild 771.93 µs/iter (573.46 µs … 2.45 ms) 763.42 µs 2.04 ms 2.16 ms
summary for small supergraph
guild
5.25x faster than apollo
• huge supergraph (100+ subgraphs)
------------------------------------------------- -----------------------------
apollo 4.48 s/iter (4.41 s … 4.53 s) 4.51 s 4.53 s 4.53 s
guild 231.71 ms/iter (217.79 ms … 265.92 ms) 232.53 ms 265.92 ms 265.92 ms
summary for huge supergraph
guild
19.32x faster than apolloJoin the Collaboration
We’re inviting developers, GraphQL enthusiasts from all corners of the world to join us in this exciting venture. Whether it’s through contributing code, reporting issues, or providing feedback, your involvement will play a pivotal role in shaping the future of this project.
Join our newsletter
Want to hear from us when there's something new? Sign up and stay up to date!
By subscribing, you agree with Beehiiv’s Terms of Service and Privacy Policy.
Recent issues of our newsletterSimilar articles
Announcing Accounts.js 1.0 Release Candidate
Introducing Accounts.js 1.0 Release Candidate, an end to end authentication and accounts management solution.
Building Open Source GraphQL Security
Learn how open-source boosts GraphQL security and explore defensive and offensive tools, resources, and best practices to protect your GraphQL APIs.
GraphQLConf 2023 Recap
Explore the highlights of GraphQLConf 2023. Learn about the latest trends in GraphQL, from gateway solutions to composite schemas and innovative projects.
State of GraphQL Gateways in 2023
A six-month journey of researching, benchmarking, exploring and comparing GraphQL gateways and the Federation spec in 2023.