Learn GraphQL federation #1826
Learn GraphQL federation #1826
Conversation
|
@kamilkisiela is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Co-authored-by: Andrew Carlson <[email protected]>
src/pages/learn/federation.mdx
Outdated
| As applications grow more complex, traditional monolithic approaches often fall short. At scale, | ||
| monolithic architectures can become cumbersome, brittle, and increasingly hard to test and validate. | ||
| This has led to a rise in the adoption of new patterns like distributed systems and microservices. | ||
| In some ways, GraphQL Federation is like microservices for GraphQL – an architectural pattern that | ||
| has found particular resonance in the GraphQL ecosystem. |
There was a problem hiding this comment.
@mjmahone I'd love to get your input on this paragraph.
There was a problem hiding this comment.
This looks like an excellent resource; thanks for your work on it!
Please play close attention to capitalisation, for example:
- "GraphQL Federation" - this is a Thing, a technology, because it is a proper noun
- "GraphQL federation" - this is a concept, an approach, it is not a proper noun
Be sure you're using the right version in each case to help the reader interpret your intent.
The capitalisation of subheadings is also inconsistent, we generally use "Sentence case" in headings rather than "Title Case" (checked via grep -R '^##' src/pages/learn/) though there are definitely exceptions we should tidy up. Really we should have a style guide for this; if you fancy setting up Vale.sh as a separate PR feel free!
I think we might need to carefully audit usage of the word "graph", and perhaps replace it with "GraphQL schema" or other clearer wording in a few places - for example:
helping establish federation as a standard architectural pattern for building a distributed graph in the GraphQL ecosystem.
Conceptually you already have a distributed graph (your business entities), and federation is instead an architectural pattern for building a single GraphQL schema that models and enables interaction with your existing distributed graph. (I wouldn't necessarily use this wording in the docs though.)
I like that you've attempted to represent balance via the Meta/Netflix/Volvo/etc comparison; however it should be noted that these companies aren't just "at scale" but are at hyper scale - they are international household names. The vast vast majority of companies and organizations are not at this scale, so I'm concerned that text such as:
As you see, many industry leaders successfully federated their GraphQL APIs, proving that it works reliably for large-scale production applications.
will encourage smaller organizations to prematurely adopt federated GraphQL techniques thinking that we're recommending it. I think some additional qualifiers might help with this:
As you see, some of the world's largest industry leaders have successfully federated their GraphQL APIs, proving that it works reliably for production applications at an extraordinary scale.
May also be worth adding text that makes it clear you don't need to start with Federation out of the gate, but can upgrade to it later when you need it (rather than starting with it just in case you need it later).
Overall I think this is excellent content - thanks again for all your efforts!
There was a problem hiding this comment.
This is excellent; the only part I'm hesitant on is the first three sentences - I'd love some feedback from @graphql/tsc on that paragraph in particular.
Thanks for your work on this @kamilkisiela 🙌
There was a problem hiding this comment.
Scratch that; though I'd still welcome the feedback of @mjmahone and @leebyron in particular, the text is accurate: monolithic approachs do often fall short, and they can become cumbersome - they don't always do these things, and there's plenty of examples of monoliths scaling massively just fine, but there's also plenty of counter-examples where microservices/etc are necessary.
|
From my experience, there are more examples of broken monoliths than unnecessary usage of Apollo Federation, but I'm fine with adjusting the sentence a bit |
I would recommend to keep this section a bit more neutral. I get the sentiment, but there is no real reason to go into the trade off discussion here. Something along the lines of "an alternative design approach to the classical monolith, often described as micro services (link to https://martinfowler.com/articles/microservices.html) has gained popularity in the last decade+". We should not argue for one or the other and leave this discussion to much better pages like the Fowler page. My 2cent. |
I thought about creating a page that explains what federation in context of GraphQL even means,
to create a good entry point for people interested in this space and looking for information.
It could help to shine more light on Composite Schema Working Group and the spec that's in progress.
The WG would have a page to explain what, how and why.
It's an initial draft, something to iterate on, think what to include etc. Happy to hear your thoughts.