
<p>The traditional approach to microservices in Kubernetes requires duplicating application logic into YAML config files. This leads to information fragmentation, inconsistencies, and ultimately bugs. With GraphQL and Apollo Federation, you can reduce the amount of required config, prevent duplication, and have a better experience maintaining your API. In particular, Apollo Federation can:</p>



<ol class="wp-block-list">
<li>Prevent conflicting API routes, and give better visibility into the entire API.</li>



<li>Ensure that routing rules always match the application code.</li>



<li>Make microservice dependencies declarative, and avoid custom networking rules between services.</li>
</ol>



<h2 class="wp-block-heading"><a href="#catch-conflicting-routes" aria-hidden="true" class="aal_anchor" id="catch-conflicting-routes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Catch conflicting routes</h2>



<p>The new Kubernetes Gateway API provides a lot of ergonomic improvements over the older Ingress, and puts more power in the hands of application developers to define their routes. While this is likely a good choice for a REST API, it can also lead to unexpected behavior.</p>



<p>Consider a backend team at a retail company who are implementing a new feature: allowing users to subscribe to a product they purchase on a regular basis. They might introduce an <code>HTTPRoute</code> rule that looks like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml">rules:
 - matches:
     - path:
         type: RegularExpression
         value: /user/[^/]+/subscription</code></pre>



<p>Unfortunately, they don’t know that the accounts team has already registered the <em>same</em> route to fetch a user’s membership (formerly called “subscription”)! When they roll out these changes, one of a few things could happen:</p>



<ul class="wp-block-list">
<li>The rule isn’t applied because the older membership route takes precedence. This is likely the preferred outcome: it doesn’t break <em>existing</em> features (and it’s what <a href="https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule">the docs</a> suggest should happen), but it can lead to head-scratching on the developers’ part. Ultimately, they’ll call in the platform team to figure out what’s going on.</li>



<li>Or, the rule <em>is</em> applied because, as is the case with the popular gateway I was testing, the alphabetical order of namespaces is used to resolve conflicts <em>without</em> considering the age of the config. This is risky business: the new feature appears to be working fine, and could pass QA despite having introduced a production issue. From here, it’s only a matter of time before the error reveals itself and someone gets paged to diagnose it.&nbsp;</li>
</ul>



<p>Neither outcome is great. Wouldn’t it be better if the products team were informed of the problem before ever deploying anything? With Apollo Federation, that’s exactly what happens.</p>



<p>First off, the developers can delete their entire <code>HTTPRoute</code>; with Federation, the same code which defines the GraphQL API of a microservice determines how routing can work. Whether locally or in CI for their pull request, the product team encounters an error when they try to build (aka “compose”) their new <code>subscription</code> field:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">INVALID_FIELD_SHARING: Non-shareable field &quot;User.subscription&quot; is resolved
 from multiple subgraphs: it is resolved from subgraphs 
 &quot;products&quot; and &quot;users&quot; and defined as non-shareable in all of them</code></pre>



<p>Not only does CI fail on the conflict and prevent them from deploying something that could potentially break production, but it also tells them which other service they’re conflicting with. These early show-stopping errors carve a much faster path to diagnosis: informing the developer what happened, and where they can go to fix it.&nbsp;</p>



<h2 class="wp-block-heading"><a href="#preventing-incorrect-path-rules" aria-hidden="true" class="aal_anchor" id="preventing-incorrect-path-rules"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Preventing incorrect path rules</h2>



<p>A lesson we learn time and time again is that there should be a single source of truth for data, and configuration is no different. With a traditional REST microservices setup, there are at least two sources of truth for routing.</p>



<p>First, the developer needs to define the route in their web framework of choice. For example, they might have this FastAPI route in a Python service:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-python">@app.get(&quot;/items/{item_id}&quot;)
async def read_item(item_id: int) -&gt; Item:
  return Item.load(item_id)</code></pre>



<p>Second, they need to redefine the route in Kubernetes config. They’ll probably end up with something closely resembling the application code:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml">rules:
 - matches:
     - path:
         type: RegularExpression
         value: /items/\d+/</code></pre>



<p>This works fine—that is, until the application updates to use opaque string IDs (like UUIDs). If the developer forgets to check on the Kubernetes config, the route will stop working. You could leave it to your QA team or some careful code review to catch this, or you could remove the possibility of this error entirely.</p>



<p>With GraphQL and Apollo Federation, the routing information all flows from a single source in the code, so it can never be out of sync! When a developer updates their microservice, the standard CI/CD process propagates that change automatically to the router, with no manual checks required. Better yet, if that change would break downstream clients, tools like <a href="https://bit.ly/3TcpBaP">Apollo GraphOS</a> catch and stop the release in its tracks before it even rolls out to the QA environment. That means less back-and-forth, and more shipping!</p>



<h2 class="wp-block-heading"><a href="#clean-up-inter-service-networking-rules" aria-hidden="true" class="aal_anchor" id="clean-up-inter-service-networking-rules"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Clean up inter-service networking rules</h2>



<p>Most of the time, the only pods that should communicate with a microservice are the API Gateway’s pods. Security best practices tell us to lock down networking to only those interactions that are required. As a result, we’ll usually start each new microservice with a <code>NetworkPolicy</code> that looks something like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml">apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
 name: microservice-network-policy
spec:
 podSelector: {}
 policyTypes:
   - Ingress
 ingress:
   - from:
       - namespaceSelector:
           matchLabels:
             name: infra
         podSelector:
           matchLabels:
             app: gateway</code></pre>



<p>Here we’re denying all ingress traffic for all pods unless it comes from the API Gateway.</p>



<p>Sometimes, though, one microservice needs data from another. Achieving this typically involves a request to the platform, infrastructure, and/or security teams to add a new rule for communication between those services. Worse, that rule will probably have to be broad enough in scope that <em>any</em> traffic is now allowed between those services,<em> loosening security</em> more than required. This direct communication also <em>tightens the coupling</em> between the microservices, making them harder to change and more likely to break.</p>



<p>With Apollo Federation, services can set up their dependencies declaratively and let the router take care of the rest. In this example, the <code>totalCost</code> field requires a <em>different</em> service’s <code>products</code> field (specifically, the <code>price</code> and <code>shipping</code> subfields).</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Order @key(fields: &quot;id&quot;) {
   id: ID!
   products: [Product] @external
   totalCost: Int @requires(fields: &quot;products { price shipping }&quot;)
}</code></pre>



<p>Not only does this microservice not need to directly communicate with another microservice, it doesn’t care <em>which</em> service provides the data it needs. This decouples the services, freeing up teams to evolve their projects independently. This process also explicitly documents dependencies, so CI can prevent changes that would cause issues for other services.</p>



<p>Only the data that is necessary for particular request will flow between microservices, and <em>everything</em> comes through the router. This means there’s a central place to monitor and manage traffic, and networking rules can be simplified and standardized. Because adding a new dependency is a simple code change, developers can submit fewer tickets to the platform and security teams and greatly reduce the risk of shipping broken code.</p>



<h2 class="wp-block-heading"><a href="#simplify-your-kubernetes-config-today" aria-hidden="true" class="aal_anchor" id="simplify-your-kubernetes-config-today"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Simplify your Kubernetes config today</h2>



<p>Using GraphQL with Apollo Federation can save time for your platform, infrastructure, and backend development teams while improving the reliability and maintainability of your microservices. It does this by removing application logic from your Kubernetes config, enabling each team to focus on what matters. If you’re interested in learning more about Apollo Federation, <a href="https://discord.gg/amVehrwMpJ">join our Discord server</a> and chat with us in the <code>#apollo-federation</code> channel. If you have any ideas for improving a microservice platform that we should check out next, we’d love to hear about that too!</p>


Remove Application Logic from Kubernetes Config


<h2 class="wp-block-heading"><a href="#introduction" aria-hidden="true" class="aal_anchor" id="introduction"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Introduction</h2>



<p>Many organizations own a Monolith (GraphQL or Non-GraphQL) and migrating away always seems an impossible task, most organizations fall into a seemingly endless amount of effort with very little progress to show for it.</p>



<p>At Apollo we have seen many different patterns of migrating away from a monolith. In this blog we will discuss the pattern which we&#8217;ve seen have the greatest success, and one which iteratively provides actual progress to the business investing in this change, all made possible by the careful application of Federation to the problem.</p>



<h2 class="wp-block-heading"><a href="#the-digital-transformation" aria-hidden="true" class="aal_anchor" id="the-digital-transformation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The digital transformation</h2>



<p>Our wide reaching experiences has led us to recommend the <a href="https://martinfowler.com/bliki/StranglerFigApplication.html" target="_blank" rel="noreferrer noopener">Strangler fig</a> pattern, which basically means placing a facade in front of your monolith (with every call to that monolith now passing through the facade), allowing you to start to dice up and remove/replace the monolith &#8211; critically &#8211; without affecting your consumers.&nbsp;</p>



<p>Using this pattern allows you to move away from the Monolith whilst critically showing incremental progress to the business, regarding removing the tech debt which currently burdens them.</p>



<p>The first thing to ask &#8211; often the hardest to answer &#8211; is how do you split the monolith up? Most companies choose to split up the monolith by domain.&nbsp;</p>



<p>Lets start with an example scenario of a typical e-commerce application and some of its possible domains.</p>



<ul class="wp-block-list">
<li>Product</li>



<li>Inventory</li>



<li>Cart</li>



<li>Order</li>



<li>Payment</li>



<li>Customer account</li>



<li>Marketing</li>
</ul>



<p>Using the domains discussed above we can see how we could view a monolith in segments relating to specific domains &#8211; in figure below</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/1.the-monolith.jpg" alt="" class="wp-image-22285" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/1.the-monolith.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/1.the-monolith-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/1.the-monolith-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 1. Your Monolith</figcaption></figure>



<p>If we look at figure 2 of a simplified and typical monolith setup, you can see how clients fetch data and how tightly bound clients are to the system. To move past this, we use Federation as the critical enabler.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/2.Typical-monolith-setup.jpg" alt="" class="wp-image-22287" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/2.Typical-monolith-setup.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/2.Typical-monolith-setup-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/2.Typical-monolith-setup-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 2. Bound to the Monolith</figcaption></figure>



<p>The key technical aspect to manage here is bringing about productive change as fast as possible, wasting as little time and money during the digital transformation.</p>



<p>The approach is to decouple the existing clients from the monolith and onto an established Interface which is afforded by the Federation layer. We are now actively removing risk of back end change from the client, thus allowing the organization to go ahead with the transformation.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/3.-First-steps.jpg" alt="" class="wp-image-22289" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/3.-First-steps.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/3.-First-steps-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/3.-First-steps-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 3. First successful subgraph migration</figcaption></figure>



<p>The API Gateway here will now allow us to fetch a data response (previously monolith) from the newly Federation architecture. Make sure to record lessons here and apply them going forward to the next subgraph.</p>



<p>Do note, that some client work <em>may</em> be required here to bind newly created or improved client operations/queries.&nbsp;</p>



<p>Now that you have gained the experience of implementing one subgraph, you are ready to transfer this knowledge to implement the second subgraph. You will find it gets easier and easier, because every new subgraph implementation will build on the learning of the last.</p>



<p>It is important to note that this pattern keeps the monolith in play purely as a data source, because you are 100% certain the data is correct. Changing everything at once forcefully cascades change across (and activating) nearly every team, which will become impossible to manage. The creation of a contract (GraphQL Schema) de-risks the migration hugely because the org can be 100% certain they can serve the original data response structures reliably.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/4.-Additional-subgraphs.jpg" alt="" class="wp-image-22291" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/4.-Additional-subgraphs.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/4.-Additional-subgraphs-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/4.-Additional-subgraphs-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 4. Learning from the first and implementing second subgraph</figcaption></figure>



<p>Note however, it is not necessary to connect to the monolith <strong>if</strong> you already have the new replacement backing microservices already available. If this is the case, you can bypass the monolith immediately and connect to that microservice.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/5.-Penultamate-state.jpg" alt="" class="wp-image-22293" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/5.-Penultamate-state.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/5.-Penultamate-state-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/5.-Penultamate-state-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 5. Strangler Fig fully applied to Monolith</figcaption></figure>



<p>Using the Strangler pattern, we will arrive at a point where all traffic for each client is actually being facaded by the supergraph itself.We are now officially in a <em>decoupled state</em>, whereby the client has no idea where the data is coming from, freeing the org to start the decommissioning phase of this pattern; shutting down the monolith section by section.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/6.-Shutting-down-monolith-sections.jpg" alt="" class="wp-image-22295" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/6.-Shutting-down-monolith-sections.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/6.-Shutting-down-monolith-sections-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/6.-Shutting-down-monolith-sections-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 6. Strangler Fig worked. New modern services implemented.</figcaption></figure>



<p>Figure 2 above demonstrates two domains which were previously served by the monolith, now being served by the new modern microservices. </p>



<p>It is critical to note, this pattern actively hides deep architectural implementational details away from the client, yet <em>still</em> fulfils the historically agreed data response, enabled entirely by contract (Schema) of our new Supergraph.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed.jpg" alt="" class="wp-image-22297" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 7. The migration is complete. The Monolith has been successfully removed.</figcaption></figure>



<p>The end state of the transformation is achieved once all the domains in the monolith have been migrated, thus allowing the org to successfully rid themselves of the monolith.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>Although moving away from a deeply entrenched monolith can seem like an impossible task, using the steps as described in this pattern and also compartmentalizing away any un-required complexity &#8211; what seems an impossible task, can be achieved in a manageable fashion.</p>



<p>Leverage the supergraph contract to decouple your system, allowing you to <strong>safely and predictably</strong> migrate away from the monolith, without impacting your clients.</p>



<p>Using Federation as a tool will greatly increase your ability to deliver this digital transformation on time and on budget; as it provides the missing link to decouple the change process of systems modernisation, between your clients and internal architecture. Head over to our <a href="https://www.apollographql.com/docs/federation/#break-up-monolithic-code">documentation</a> to learn more of how you can break up your monolith and incrementally adopt Federation 🙌</p>


From Monolith to Federation

Federated subscriptions in GraphOS: real-time data at scale

Add Rust to your GraphQL API with GraphOS

Add Python to your GraphQL API with GraphOS and Strawberry GraphQL

Announcing Apollo Router v1.0

Federated Schema Design, a part of the Apollo Federation Best Practices Series

Federated Schema Design


<p>Whether you are a large company or a single developer, we all want to know the best way to design an effective architecture – the schemas, services, folders, and so on. We find ourselves asking “Should we start with a modular monolith? Should we use microservices?”</p>



<p>These early architectural questions are important because they affect so many aspects of the way we work, making it easier or harder to divide work, understand the code, and scale-up in the future.</p>



<p>Before we can explore some of the more nuanced, technical topics, we need to learn some basics ways to think about a federated architecture.&nbsp;</p>



<p>In this post, we’re going to learn what federated architecture is and why we would want to use it.</p>



<h2 class="wp-block-heading"><a href="#what-is-a-federated-architecture-in-graphql" aria-hidden="true" class="aal_anchor" id="what-is-a-federated-architecture-in-graphql"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What is a federated architecture in GraphQL?</h2>



<p>When developing a GraphQL monolith, the architecture is straightforward. Clients talk to your GraphQL monolith, and that monolith connects to the various data sources you have. The GraphQL server determines what data sources to interact with based on the incoming query and the necessary resolvers. We typically represent the details of some parent type or fields in a downstream resolver using some bit of code in the project.</p>



<p>Each GraphQL server provides a portion of the schema in the overall graph in a federated architecture. We call these GraphQL servers <strong>subgraphs</strong>. We can combine these subgraphs through metadata defined in their schemas to establish relationships in the graph:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="322" src="https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-1024x322.png" alt="" class="wp-image-12929" srcset="https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-1024x322.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-300x94.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-768x241.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-1536x482.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-2048x643.png 2048w, https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-1200x377.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/04/Screen-Shot-2022-04-04-at-3.08.03-PM-2-1980x622.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>A fundamental difference between a federated architecture and a monolith is that we define the relationships defined in our graph using metadata, not additional logic in our resolvers. Let&#8217;s take a simple Products and Reviews query as an example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query ProductsWithReviews {
  products {
    name
    reviews {
      content
    }
  }
} </code></pre>



<p>In a monolith, we’ll need to ensure the resolver for “reviews” has access to the individual product id. This can get even more complicated as the monolith grows and a Review resolver is shared in more places in the schema.</p>



<p>In a federated architecture, the Product type would live in the products subgraph and be identified with metadata to identify the key fields for it. We would consider the Product type as an <strong>Entity </strong>and it would be denoted with the <code>@key</code> directive:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># Products Subgraph
type Product @key(fields:”id”){
  id: ID!
  name: String
}</code></pre>



<p>There would also be a reviews subgraph responsible for the reviews information. It would use the Product directly and add the appropriate fields for the graph:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># Reviews Subgraph
type Product @key(fields:”id”){
  id: ID! @external
  reviews: [Review]
}
type Review {
  content: String
}</code></pre>



<p>Now in the reviews subgraph is responsible for providing the data it can without having to worry about any of the other details surrounding the Product type. Each subgraph represents the schema they can provide data for and these are combined to create the <strong>supergraph</strong>.</p>



<p>The <strong>supergraph</strong> knows all of the data and operations across all of your schemas and where to find them, whether that’s in a remote URL or a file in a git repository. Using the <a href="https://www.apollographql.com/docs/router">router</a>, the supergraph figures out the most efficient path to fetch the relevant data. The best part is that the supergraph doesn’t look any different than a regular GraphQL endpoint. It just combines all the data in a structured, easy-to-use way.</p>



<p>Now that we understand a little more about what a federated architecture is, why would we want to use it? We should start by looking at the start of our GraphQL journey, the GraphQL monolith.&nbsp;</p>



<h2 class="wp-block-heading"><a href="#the-journey-of-a-graphql-monolith" aria-hidden="true" class="aal_anchor" id="the-journey-of-a-graphql-monolith"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The journey of a GraphQL Monolith</h2>



<p>Our first implementation of a monolithic graph was great, but as it grew, we started to see problems. The initial schema and use cases were simple, and we could create relationships in our schema that connect to various APIs by how we defined our field and type resolvers.&nbsp;</p>



<p>New use cases grew our schema along with our resolvers. The pattern of passing data through our resolvers becomes increasingly essential, and we often realize it once it&#8217;s too late. Maybe some teams have just thrown data on the request&#8217;s context, and the memory footprint of our instances runs out of control. Often, we introduce complexity into the resolvers, and they tend to cascade into each other.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="456" src="https://wp.apollographql.com/wp-content/uploads/2022/04/Apollo-Federation-Best-Practices-Series-2-1-1024x456.png" alt="" class="wp-image-12927" srcset="https://wp.apollographql.com/wp-content/uploads/2022/04/Apollo-Federation-Best-Practices-Series-2-1-1024x456.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/04/Apollo-Federation-Best-Practices-Series-2-1-300x134.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/04/Apollo-Federation-Best-Practices-Series-2-1-768x342.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/04/Apollo-Federation-Best-Practices-Series-2-1.png 1115w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Type resolvers are defined to help integrate into a specific API, but as we use a type in other places within our schema, a resolver could be used in more than one place. This could cause that resolver to grow with some code to check expected parent values. We just want some simple expected inputs to provide to the underlying data source for that type, and the mixed-use in our monolith can grow in a way that requires &#8220;tribal knowledge&#8221; of how the graph is designed.</p>



<p><strong>“Too big” monolith</strong></p>



<p>We should celebrate the success and growth of our GraphQL initiative. Whether you&#8217;re a single dev or a large organization, GraphQL is the future. We&#8217;ve seen this pain for monolithic graphs when they grow &#8220;too big&#8221;. &#8220;Too big&#8221; is differs by project, though, and it&#8217;s dependent on factors like the number of devs and its overall success.&nbsp;</p>



<p>When we had a monolith at Apollo, it became increasingly difficult to onboard new members to the project because there was an enormous scope of what you might encounter. Setup and running may be simple, but successfully navigating the code to implement a new feature is challenging. For a new developer trying to build their first new feature, starting from a templated server simplifies the scope of what they need to know.</p>



<p><strong>Backend for Frontend (BFF) Monoliths</strong></p>



<p>Some projects are large enough that the web and mobile teams have built separate GraphQL backends, each as a monolith. This could have naturally grown from the team&#8217;s desire to move quickly and separately from each other. These bodies of work often overlap with each other and don&#8217;t share learnings as easily. There probably is a good reason why one team did something differently, and instead of having that learning standardized into the graph, it gets siloed into one team&#8217;s BFF. The BFF pattern also has similar &#8220;too big&#8221; potential pitfalls for each team, but a need to standardize within the organization is typically the larger driver.&nbsp;</p>



<p><strong>GraphQL Microservices with handwritten gateway code</strong></p>



<p>Many projects felt these growing pains of a GraphQL monolith and ventured into GraphQL microservices. We did this by writing some code in a GraphQL gateway that would &#8220;stitch&#8221; together multiple GraphQL schemas: schema stitching. Schema stitching gave a new level of coordination that the monolith was missing. The web team and mobile team can combine their efforts by just trying to add their BFF schemas together. Gateway teams and committees started everywhere to provide a level of governance not out of desire but out of necessity.</p>



<p>Combining multiple schemas can result in numerous problems. You would think you could pull together any schema, but how do you handle things like naming conflicts or mismatches in shared types? What if both teams have the same type defined but drastically different representations? You have to decide how you&#8217;re going to combine all this together and make some decisions about collaboration in contributing to the graph. The gateway team would often help other new efforts join the graph.</p>



<p>Sometimes, a query would have an issue, and getting to the bottom of it could be an extremely painful exercise. A client team reports that their query is returning much slower now and they didn&#8217;t change anything on their end. How does the incoming query even execute? You probably have some performance monitoring and tracking information, but which GraphQL microservices were called and in what order? It could even be that the merging flow changed, which has an impact on the overall execution. I may have spent a day in the past tracking an error down to this exact problem 🤦.</p>



<p>We also had to think about how to handle updating our gateway when there were changes to any GraphQL microservice schema. This meant crafting a solution either built off Introspection queries or some cloud file storage solution. Eventually, the day comes when your graph has some downtime due to a team pushing a breaking change. The breaking change most commonly comes in the GraphQL microservice deployment succeeding only to have the gateway fail on startup because it had type merging errors.</p>



<h2 class="wp-block-heading"><a href="#why-apollo-federation" aria-hidden="true" class="aal_anchor" id="why-apollo-federation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Why Apollo Federation?</h2>



<p>We designed Apollo Federation to solve the common monolithic pitfalls and to prevent having to rely on brittle code to merge multiple schemas. Now, we can combine schemas into a supergraph in a declarative way. We can define relationships in our graph using nothing other than types, just like we expect to.&nbsp;</p>



<p>Separation of concerns is a core principle of Apollo Federation because it allows each team to deal with its own subgraph. Federation ultimately increases team productivity and collaboration because they can see the relationships defined in the schema and quickly understand points they can collaborate on. Each subgraph only has to deal with the schema it represents. Federation also cuts down on breaking changes and communication while maintaining the necessary collaboration based on the defined metadata. Federation makes the development process simpler by being able to focus on the portion of the schema you&#8217;re implementing.&nbsp;</p>



<p>Along with having a modularized graph, we also gained the ability to scale our subgraph instances independently. In a monolith, you could only scale the entire monolith. With Apollo Federation, we can scale subgraphs independently and even architect subgraphs for expected loads. For example, people look at products more than they are using the &#8220;checkout&#8221;. Running these pieces of functionality in their own subgraphs enables us to scale them independently. We can even define independent caching strategies for our subgraphs if needed.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>Eventually, the monolith outgrows what it was initially designed for, and we find ourselves trying out GraphQL microservices. Apollo Federation provides a flexible architecture that enables you to scale your graph and define relationships through metadata defined in your schema. Federation removes the need for any handwritten code to &#8220;glue&#8221; together multiple GraphQL microservices. With federation, you can responsibly share ownership of your graph across any number of subgraphs. No single subgraph controls every aspect of a type; instead, we distribute the definition across codebases rather than centralize it. And since it&#8217;s just GraphQL, you can <a href="https://www.apollographql.com/docs/federation/v2/federation-spec/">build your subgraphs in any language</a>.</p>



<h2 class="wp-block-heading"><a href="#continue-reading" aria-hidden="true" class="aal_anchor" id="continue-reading"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Continue Reading</h2>



<p><a href="https://www.apollographql.com/blog/federated-schema-design/">Federated Schema Design Principles</a> </p>



<p>Have an idea for another guide you’d like to see? Use the feedback form below to suggest another topic! Have an idea for another guide you’d like to see? Use the feedback form below to suggest another topic!</p>


Introduction to Apollo Federation, part of the Apollo Federation Best Practices Series

Introduction to Apollo Federation


<p>Building a graph can feel daunting, regardless of whether you&#8217;re working on a new project or a large enterprise trying to bring it all together. Bringing everything into one graph brings up various questions: What APIs are made available for clients? How many services do existing clients talk to? How are these services related?</p>



<p>Apollo Federation provides the possibility of solving these concerns through a domain-oriented graph, which allows you to elevate your graph from just another API to a platform that exposes the value of your product.</p>



<p>Apollo Federation provides a developer-friendly path to GraphQL microservices for any project, whether you&#8217;re a single developer or a large organization. Since its inception, I&#8217;ve been helping customers with Apollo Federation, and that&#8217;s why I&#8217;ve started the Apollo Federation best practices series. To help you overcome the most common challenges devs face when designing, building, and scaling federation in the wild.</p>



<h2 class="wp-block-heading"><a href="#our-advice" aria-hidden="true" class="aal_anchor" id="our-advice"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Our Advice</h2>



<p>At the heart of Apollo Federation is a thin<a href="https://www.apollographql.com/docs/federation/federation-spec/"> open-sourced specification</a> that makes it possible to modularize your graph into smaller parts using entities and subgraphs. Linking subgraphs together using the <code>@key</code> directive, we compose them into a <strong>supergraph</strong>. We believe the supergraph provides a new strategic advantage for devs building with GraphQL, but first, we should discuss the questions that lead us to this conclusion.&nbsp;</p>



<p>What is a supergraph? What is the architectural difference between a monolith and a supergraph? Why would we want to break down our current monolithic architecture? What are the advantages of a supergraph? How is designing a federated schema different from a single schema? What about deploying a federated graph and proper security for my subgraphs?</p>



<p>This series is a curation of our advice on why you should embrace a distributed architecture and how you can be successful with Apollo Federation.</p>



<h2 class="wp-block-heading"><a href="#where-should-i-start" aria-hidden="true" class="aal_anchor" id="where-should-i-start"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Where should I start?</h2>



<p>If you’re rusty or unfamiliar with GraphQL, I’d recommend first walking through the getting started guide for Apollo Server and taking the <a href="https://odyssey.apollographql.com/lift-off-part1">Lift-off course in Odyssey</a>.</p>



<p>After that, check out the posts from the series in order.</p>



<h2 class="wp-block-heading"><a href="#start-reading" aria-hidden="true" class="aal_anchor" id="start-reading"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Start reading</h2>



<ol class="wp-block-list"><li><a href="https://www.apollographql.com/blog/introduction-to-apollo-federation">Introduction to Apollo Federation</a></li><li><a href="https://www.apollographql.com/blog/federated-schema-design/">Federation schema design principles</a> </li></ol>


Introducing the Apollo Federation Best Practices Series


<p>The momentum continues to build around Apollo Federation with over 1M weekly downloads and 18K+ projects now using Apollo Federation, up 50% in the last 5 months since <a href="https://www.apollographql.com/blog/announcement/backend/announcing-federation-2/">Federation 2 was first announced</a>.&nbsp;</p>



<p>We’d like to extend a big thank you to our community! Because of your contributions, Federation developers can compose subgraphs written in <a href="https://www.apollographql.com/docs/federation/v2/other-servers">over 18 languages and frameworks</a>!</p>



<p><strong>Today, we’re excited to announce the general availability of Apollo Federation 2, with improvements across the entire Apollo platform including Gateway 2.0, the Rover CLI, and Apollo Studio.</strong>&nbsp;</p>



<p>Keep reading to learn more about Federation and what you can expect from the new improvements in Federation 2 or head to our docs to <a href="https://www.apollographql.com/docs/federation/v2/">get started today</a>! 🚀</p>



<h2 class="wp-block-heading"><a href="#whats-new-in-apollo-federation-2" aria-hidden="true" class="aal_anchor" id="whats-new-in-apollo-federation-2"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What&#8217;s new in Apollo Federation 2</h2>



<p>Apollo Federation is a <a href="https://www.apollographql.com/docs/federation/v2">modular GraphQL architecture</a> that powers the world’s most important graphs, including <a href="https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-2-bbe71aaec44a">Netflix</a>, <a href="https://medium.com/walmartglobaltech/federated-graphql-walmart-bfc85c2553de">Walmart</a>, <a href="https://medium.com/adobetech/graphql-making-sense-of-enterprise-microservices-for-the-ui-46fc8f5a5301">Adobe</a>, and <a href="https://www.apollographql.com/docs/federation/enterprise-guide/federation-case-studies/">more</a>.&nbsp;</p>



<p>Designed in collaboration with the GraphQL community, Federation 2 is a clean-sheet implementation of the core composition and query-planning engine at the heart of Apollo Federation.&nbsp;</p>



<p>The new version builds on the success of the original with an improved shared ownership model, enhanced type merging, and cleaner syntax for a smoother developer experience. It’s backward compatible and designed for incremental adoption one subgraph at a time.</p>



<h3 class="wp-block-heading"><a href="#build-with-a-smoother-developer-experience" aria-hidden="true" class="aal_anchor" id="build-with-a-smoother-developer-experience"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Build with a smoother developer experience</h3>



<p>Federation 2 adds first-class support for shared interfaces, enums, and other value types. Common tasks like extending a federated type are now possible without special directives and keywords, resulting in cleaner syntax.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1999" height="798" src="https://wp.apollographql.com/wp-content/uploads/2022/04/image2.png" alt="" class="wp-image-13169" srcset="https://wp.apollographql.com/wp-content/uploads/2022/04/image2.png 1999w, https://wp.apollographql.com/wp-content/uploads/2022/04/image2-300x120.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/04/image2-1024x409.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/04/image2-768x307.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/04/image2-1536x613.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/04/image2-1200x479.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/04/image2-1980x790.png 1980w" sizes="(max-width: 1999px) 100vw, 1999px" /></figure>



<h3 class="wp-block-heading"><a href="#deliver-smaller-increments-with-better-shared-types" aria-hidden="true" class="aal_anchor" id="deliver-smaller-increments-with-better-shared-types"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Deliver smaller increments with better shared types</h3>



<p>Apollo Federation’s shared ownership model lets you spread a federated type across subgraphs so that you can reuse common value types like interfaces and enums. Federation 2 improves upon the shared ownership model and makes shared types more flexible:</p>



<p><strong>Value type definitions are now merged into a single unified type</strong>. Value types don’t need to be identical across subgraphs, so smaller incremental changes, like adding a field, can often be rolled out one subgraph at a time by using the <code>@inaccessible</code> directive to hide it from the client-facing schema.</p>



<p><strong>All types are shared equally across subgraphs</strong>. This means you don’t have to use the <code>extend</code> keyword.</p>



<p><strong>All fields have a single source of truth by default. </strong>You can optionally mark a field or object with the <code>@shareable</code> directive&nbsp; so other subgraphs can resolve them, which may increase performance.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1999" height="874" src="https://wp.apollographql.com/wp-content/uploads/2022/04/image3.png" alt="" class="wp-image-13171" srcset="https://wp.apollographql.com/wp-content/uploads/2022/04/image3.png 1999w, https://wp.apollographql.com/wp-content/uploads/2022/04/image3-300x131.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/04/image3-1024x448.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/04/image3-768x336.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/04/image3-1536x672.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/04/image3-1200x525.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/04/image3-1980x866.png 1980w" sizes="(max-width: 1999px) 100vw, 1999px" /></figure>



<h3 class="wp-block-heading"><a href="#migrate-fields-across-subgraphs-without-downtime-or-coordinated-delivery" aria-hidden="true" class="aal_anchor" id="migrate-fields-across-subgraphs-without-downtime-or-coordinated-delivery"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Migrate fields across subgraphs without downtime or coordinated delivery</h3>



<p>As the shape of your subgraphs change, sometimes fields need to be migrated from one subgraph to another. This previously required a coordinated release across subgraphs to avoid downtime. </p>



<p>With Federation 2, field migration is painless. Simply add the field to the destination subgraph, mark it with <code>@override</code> to accept production traffic without downtime, and remove the migrated field from the old subgraph.</p>



<h3 class="wp-block-heading"><a href="#catch-errors-sooner-with-improved-static-analysis" aria-hidden="true" class="aal_anchor" id="catch-errors-sooner-with-improved-static-analysis"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Catch errors sooner with improved static analysis</h3>



<p>Federation 2 has deeper static analysis, better error messages, and a new generalized composition model that helps you catch more errors at build-time instead of at runtime. The rewritten composition engine now validates all theoretically possible queries and provides more descriptive error messages when a query can’t be satisfied. New composition hints help you understand how schema definitions influence query planning and performance.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1999" height="945" src="https://wp.apollographql.com/wp-content/uploads/2022/04/image1.png" alt="" class="wp-image-13173" srcset="https://wp.apollographql.com/wp-content/uploads/2022/04/image1.png 1999w, https://wp.apollographql.com/wp-content/uploads/2022/04/image1-300x142.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/04/image1-1024x484.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/04/image1-768x363.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/04/image1-1536x726.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/04/image1-1200x567.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/04/image1-1980x936.png 1980w" sizes="(max-width: 1999px) 100vw, 1999px" /></figure>



<p>While Federation 2 is backwards compatible, its enhanced validation might <a href="https://www.apollographql.com/docs/federation/v2/federation-2/backward-compatibility#breaking-changes">catch a few things</a> that the original Federation didn’t. Things you’ll be happy to know about!</p>



<h2 class="wp-block-heading"><a href="#getting-started" aria-hidden="true" class="aal_anchor" id="getting-started"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Getting started</h2>



<p>⚠️ <strong>Note: The Apollo Contracts preview does not yet support Federation 2. If you are using Contracts in production you should not upgrade to Federation 2 yet. The generally available release of Contracts will include support for Federation 2.</strong></p>



<p>Moving to Federation 2 is a simple and incremental process:</p>



<ol class="wp-block-list"><li><strong>Upgrade your Gateways to version 2.0.0 or later.</strong> Gateway 2 is backward compatible with Federation 1 and any existing customizations you have, so this won’t break anything.</li><li><strong>Turn on Federation 2 composition</strong> for the Rover CLI and Apollo Studio. Federation 2 composition will automatically convert Federation 1 subgraphs, so you can get some great benefits (like improved error messages) without upgrading any subgraphs! 🎉</li><li><strong>Upgrade individual subgraphs to Federation 2 syntax at your own pace</strong>. Because Federation 2 composition is backward compatible with Federation 1 subgraphs, you can add Federation 2 syntax to your subgraphs at your own pace.</li></ol>



<p>💡 You can find detailed instructions for the steps above in our <a href="https://www.apollographql.com/docs/federation/v2/federation-2/moving-to-federation-2"><strong>migration guide</strong></a>.</p>



<h2 class="wp-block-heading"><a href="#whats-next" aria-hidden="true" class="aal_anchor" id="whats-next"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What’s next</h2>



<p>If you&#8217;re already using Apollo Federation 1.x, check out <a href="https://www.apollographql.com/docs/federation/v2/federation-2/moving-to-federation-2">our migration guide docs</a> to start taking advantage of the benefits from Federation 2. If you&#8217;re interested in trying things out, check out our <a href="https://www.apollographql.com/docs/federation/v2/quickstart/setup">quickstart docs</a> or our full <a href="https://github.com/apollographql/supergraph-demo-fed2">supergraph demo for Federation 2</a> that includes a complete enterprise-grade example.</p>



<p>Check out our public <a href="https://github.com/apollographql/federation/blob/main/ROADMAP.md">Federation Roadmap</a> to learn about&nbsp; upcoming releases. We’d love to hear your thoughts! <a href="https://github.com/apollographql/federation/issues">Open a GitHub issue</a> to share your feedback.</p>



<h2 class="wp-block-heading"><a href="#get-involved" aria-hidden="true" class="aal_anchor" id="get-involved"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Get involved!</h2>



<p>If you’re interested in getting involved or becoming a contributor,&nbsp; checkout our GitHub repos and community forums:</p>



<ul class="wp-block-list"><li><a href="https://github.com/apollographql/federation">GitHub</a></li><li><a href="https://community.apollographql.com/">Apollo Community Forum</a></li><li><a href="https://community.apollographql.com/t/apollo-federation-2-compatibility-showcasing-community-libraries/3272">Subgraph Library Maintainer Support</a></li></ul>



<p></p>


Apollo Federation 2 is now generally available


<p>At last year’s GraphQL Summit we announced the alpha release of <a href="https://www.apollographql.com/blog/announcement/backend/apollo-router-our-graphql-federation-runtime-in-rust/">Apollo Router</a> for the first time &#8211; our new, high-performance Federation runtime written in Rust. Today, we’re excited to bring Apollo Router out of Alpha and into an open preview!</p>



<h2 class="wp-block-heading"><a href="#what-does-the-apollo-router-preview-mean-for-you" aria-hidden="true" class="aal_anchor" id="what-does-the-apollo-router-preview-mean-for-you"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What does the Apollo Router preview mean for you?</h2>



<p>If you’re currently running a federated supergraph with Apollo Gateway, Apollo Router gives you a leaner, high-performance runtime option for Federation (both Federation 1 and <a href="https://www.apollographql.com/blog/apollo-federation-2-and-gateway-2-0-are-now-available-in-preview">Federation 2</a>!). Here are a few things to know about the preview release:</p>



<ul class="wp-block-list"><li>Benchmarks show that Apollo Router is <strong>10x faster</strong>, has<strong> 10x higher throughput</strong>, and has <strong>12x less variance</strong> compared to the latest release of Apollo Gateway.</li><li>Apollo Router is ready for use with limited production workloads and proof-of-concepts.</li><li>You can deploy Apollo Router as a standalone binary, making it easier to manage and scale.</li><li>The preview release adds support for more advanced configuration and customization.<ul><li>Simple <a href="https://www.apollographql.com/docs/router/customizations/overview">YAML configuration</a> for CORS, logging, header propagation, routing URLs, OpenTelemetry, and operation usage reporting to Apollo Studio</li><li><a href="https://www.apollographql.com/docs/router/customizations/native">Native Rust plugins for the Apollo Router</a> for maximum flexibility &amp; control.</li><li><a href="https://www.apollographql.com/docs/router/customizations/rhai">Lightweight Rhai scripting</a> for string manipulation, custom header forwarding, and more to come as we fully develop this capability.</li></ul></li><li>Apollo Router offers key integrations with Apollo Studio:<ul><li>Automated supergraph rollout via <a href="https://www.apollographql.com/docs/router/managed-federation/overview">Managed Federation</a> and Apollo Uplink</li><li>Operation-usage &amp; client-awareness reporting via <a href="https://www.apollographql.com/docs/router/configuration/spaceport">a new reporting agent called spaceport</a></li></ul></li><li>Automatic Persisted Queries (APQ) is enabled by default with zero config required and a local, in-memory cache.<ul><li>Existing clients that use APQ will work with Apollo Router which stores persisted queries in an in-memory cache.</li><li>For an overview of the APQ protocol and Client configuration see: <a href="https://www.apollographql.com/docs/apollo-server/performance/apq/">https://www.apollographql.com/docs/apollo-server/performance/apq/</a>&nbsp;</li></ul></li></ul>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="634" src="https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D-1024x634.png" alt="" class="wp-image-12779" srcset="https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D-1024x634.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D-300x186.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D-768x475.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D-1536x950.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D-1200x743.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/03/85CCA2D7-DD89-4486-ACDB-CC551769671D.png 1600w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>Apollo Router and Gateway response time</figcaption></figure>



<h2 class="wp-block-heading"><a href="#deploying-apollo-router" aria-hidden="true" class="aal_anchor" id="deploying-apollo-router"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Deploying Apollo Router</h2>



<p>You may be wondering, “how do I get started with Apollo Router?” Good news! Unlike Apollo Gateway, Apollo Router is a standalone binary that’s purpose-built for running federated schemas, so it’s easy to deploy and scale. There are just three steps to get started:</p>



<ol class="wp-block-list"><li>Download Apollo Router</li><li>Make sure your project has a supergraph schema</li><li>Run Apollo Router 🚀</li></ol>



<p>It’s that easy! For the full quickstart guide including downloads and detailed instructions, check out <a href="https://www.apollographql.com/docs/router/">our docs</a>.</p>



<h2 class="wp-block-heading"><a href="#apollo-router-extensibility" aria-hidden="true" class="aal_anchor" id="apollo-router-extensibility"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Apollo Router extensibility</h2>



<p>Using our example is a great way to get started, but if you’ve ever run a supergraph in production with Apollo Gateway, you may have encountered a&nbsp; common challenge: how do you extend your gateway to meet your specific needs. The Gateway has a well-documented extensibility model, but you need to know node.js to take full advantage of it.</p>



<p>With Apollo Router, we want to make extensibility more approachable, which is why plugins can be configured with just a `router.yaml` file. Apollo Router is written in Rust, but things like propagating headers to subgraphs and OpenTelemetry can be configured with the `router.yaml` file without writing any Rust code, with more plugins coming soon.</p>



<p>However, we know that not every use case can be covered with pre-built customizations, so Router also supports lightweight <a href="https://www.apollographql.com/docs/router/customizations/rhai">Rhai scripting</a>. When YAML configuration is insufficient, Rhai scripting allows you to make programmatic customizations without requiring you to recompile the router with a custom Rust plugin.</p>



<h2 class="wp-block-heading"><a href="#where-to-next" aria-hidden="true" class="aal_anchor" id="where-to-next"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Where to next?</h2>



<p>We’re so excited to have the GraphQL community get their hands on the Apollo Router preview release! It’s going to be a game-changer for building high-performance supergraphs that power the world’s most cutting-edge and creative applications.&nbsp;</p>



<p>When you’re using the preview, please don’t hesitate to drop us your questions and feedback in the Apollo Router <a href="https://github.com/apollographql/router/discussions">GitHub discussion</a> &#8211; it will help us put the final touches on Apollo Router before our GA release 🚀</p>


Apollo Router: our new high-performance Federation runtime is now available in open preview


<p><em>🚀 🎉  Heads up &#8211; Federation 2 and Gateway 2.x are now GA! Check out the <a href="https://www.apollographql.com/blog/apollo-federation-2-is-now-generally-available/" data-type="URL" data-id="https://www.apollographql.com/blog/apollo-federation-2-is-now-generally-available/">GA announcement blog</a> or head over to the <a href="https://www.apollographql.com/docs/federation/" data-type="URL" data-id="https://www.apollographql.com/docs/federation/">Federation docs</a> to get started.</em></p>



<hr class="wp-block-separator"/>



<p>Four months ago we announced Apollo Federation 2 &#8211; the next generation of Federation with <a href="https://www.apollographql.com/blog/announcement/backend/announcing-federation-2/">new features</a> designed to improve the graph developer experience and make it easy for anyone to build, manage, and scale a unified graph. </p>



<p>Since then, we’ve been collecting feedback from members of the community and our customers that have tried out the alpha release and have been iterating on the Federation 2 spec to make it viable for the larger GraphQL ecosystem.&nbsp;</p>



<p>With the improvements we’ve made in recent months, we’re excited to move <a href="https://www.apollographql.com/docs/federation/v2/">Federation 2</a> along with <a href="https://www.apollographql.com/docs/federation/v2/gateway/">Apollo Gateway 2.0</a> out of alpha into public preview!</p>



<h2 class="wp-block-heading"><a href="#what-you-need-to-know-about-the-preview" aria-hidden="true" class="aal_anchor" id="what-you-need-to-know-about-the-preview"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What you need to know about the preview</h2>



<p>With Federation 2 and Gateway 2.0 now in preview, here are some highlights and improvements to be aware of:</p>



<ul class="wp-block-list"><li>There are <strong>no breaking changes</strong> between Federation 2 alpha and preview.</li><li>Apollo Gateway 0.X does not support Federation 2. If you would like to use Apollo Gateway with Federation 2, you must use Gateway 2.0 or higher.</li><li>Graphs in Apollo Studio with Federation 2 composition enabled will automatically be updated from <code>alpha</code> to <code>preview</code>.</li><li>If you have Federation 2 composition enabled, Federation 1 subgraphs will automatically be converted to Federation 2 during composition. You can continue to use your Federation 1 subgraphs as long as you like.</li><li><code>@link</code> and <code>@shareable</code> are now supported in the Fed 2 subgraph syntax.</li><li><code>subgraph-js</code> subgraph library now supports Fed 2 subgraph syntax.</li></ul>



<h2 class="wp-block-heading"><a href="#getting-started-with-federation-2-gateway-2-0" aria-hidden="true" class="aal_anchor" id="getting-started-with-federation-2-gateway-2-0"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Getting started with Federation 2 &amp; Gateway 2.0</h2>



<p>Ready to start using Federation 2? <strong>Check out our </strong><a href="https://www.apollographql.com/docs/federation/v2/federation-2/moving-to-federation-2"><strong>docs on moving to Federation 2</strong></a><strong>.</strong> Here’s a quick overview of the steps you’ll need to take:</p>



<h3 class="wp-block-heading"><a href="#1-upgrade-apollo-gateway" aria-hidden="true" class="aal_anchor" id="1-upgrade-apollo-gateway"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>1. Upgrade <code>@apollo/gateway</code></h3>



<p>To use Federation 2, you must be using Gateway 2.0 or higher (or <a href="https://www.apollographql.com/blog/announcement/backend/apollo-router-our-graphql-federation-runtime-in-rust/">Apollo Router</a>). Upgrading from Gateway 0.X to Gateway 2.0 is as easy as bumping the version in your <code>package.json</code>.</p>



<p>Gateway 2.0 is still compatible with Federation 1, so you can upgrade without breaking your existing graph.</p>



<h3 class="wp-block-heading"><a href="#2-turn-on-federation-2-composition" aria-hidden="true" class="aal_anchor" id="2-turn-on-federation-2-composition"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>2. Turn on Federation 2 composition</h3>



<p>Once your runtime is compatible with Federation 2, you’ll need to take a moment to turn on Fed 2 composition for Managed Federation or for the Rover CLI, depending on how you compose your federated graph.</p>



<p>Federation 2 composition is backward compatible with Federation 1 subgraphs (🎉), so turning it on won’t break your existing graph.</p>



<p><strong>Managed Federation</strong></p>



<p>If you use managed Federation, you can turn on Fed 2 composition for specific variants. Navigate to the “Manage Variants” section of your graph’s settings page and click the meatball menu next to a variant.</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh5.googleusercontent.com/qfapzHPkVsn7KDhBrs-x-CRWPT1yLOiu5BzS3krUHAXpC489sApWL5jqf4F64vbc79HMR1AQPnrpECb3-63vTRgt_baqGdHr-1yy6zRbl6majExI73FaiiBif4o63_wZWOwj4vsZ" alt=""/></figure>



<p>Click “Edit Build Configuration” and select Federation 2 under the “Federation Version” dropdown.</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh4.googleusercontent.com/cTbU2CnbeZa_gWjO7QkZ4Phh3o97axRZCBAcazYIaidBBkExnwACRqTGtSgXiWYwg829jE4UM-lQiVk0NOnnk_QYwswQJq_Wh5b5QUEXycbCE9ISYs8Scfp4pAdHd4cPbMe7NZ-Z" alt=""/></figure>



<p><strong>Rover CLI</strong></p>



<p>If you use the Rover CLI for Federation composition, you’ll need to install the latest version of Rover and install the Federation 2 plugin. You can find detailed instructions on how to do so <a href="https://www.apollographql.com/docs/federation/v2/federation-2/moving-to-federation-2/#using-the-rover-cli">here</a>.</p>



<h3 class="wp-block-heading"><a href="#3-modify-your-subgraphs-at-your-own-pace" aria-hidden="true" class="aal_anchor" id="3-modify-your-subgraphs-at-your-own-pace"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>3. Modify your subgraphs at your own pace</h3>



<p>At this point, your graph is already running on Federation 2 &#8211; congrats! Now, to make the most out of Fed 2, you’ll want to modify your subgraphs to take advantage of its more flexible composition model.&nbsp;</p>



<p>Since Fed 2 composition is backwards compatible with Fed 1 subgraphs, service teams can modify their subgraphs at their own pace without breaking composition! You can learn about all of the improvements available in the Fed 2 subgraph syntax in the <a href="https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2/#more-flexible-composition">documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#whats-next" aria-hidden="true" class="aal_anchor" id="whats-next"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What’s next?</h2>



<p>We can’t wait for you to experience the next generation of Apollo Federation and Gateway 2.0! 🚀&nbsp;If you’re currently using Federation 1, check our guide on <a href="https://www.apollographql.com/docs/federation/v2/federation-2/moving-to-federation-2/">moving to Federation 2</a>, or if you’re new to Federation, our <a href="https://www.apollographql.com/docs/federation/v2/quickstart/setup/">quickstart guide</a> is a great place to get started. And don’t forget, we would love to know about your experience with Federation 2, so be sure to leave us your thoughts on <a href="https://community.apollographql.com">community.apollographql.com</a>.</p>


Apollo Federation 2 and Gateway 2.0 are now available in preview


<p>With the release of Apollo Server 3.6, we introduced new features and configuration to improve usage reporting to Apollo Studio. They are companion features to Inline Tracing for federated GraphQL APIs and OpenTelemetry support. With operation shape-based usage reporting, you get a clearer picture of how your graph is used with a much smaller impact on overall performance.</p>



<h2 class="wp-block-heading"><a href="#a-brief-history-of-tracing-and-usage-reporting" aria-hidden="true" class="aal_anchor" id="a-brief-history-of-tracing-and-usage-reporting"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>A brief history of tracing and usage reporting</h2>



<p>One of my favorite benefits of GraphQL is the fine-grained usage information you get when clients must specify the fields they need in the query language. When I started using Apollo Studio, one of the features I was most excited about was access to all this data:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="647" height="727" src="https://wp.apollographql.com/wp-content/uploads/2022/02/screenshots2.png" alt="" class="wp-image-12222" srcset="https://wp.apollographql.com/wp-content/uploads/2022/02/screenshots2.png 647w, https://wp.apollographql.com/wp-content/uploads/2022/02/screenshots2-267x300.png 267w" sizes="(max-width: 647px) 100vw, 647px" /><figcaption>Screenshots of the Fields page showing field usage and the Operations page showing resolver traces</figcaption></figure>



<p>At the time, both of these views were powered by <em>tracing</em>.</p>



<p>Tracing is a means of collecting detailed, low-level information for investigating and diagnosing issues and performance. In a GraphQL service, we usually refer to “resolver tracing”, which tracks the time spent and the errors that occur with in field resolver functions.</p>



<p>In a monolithic GraphQL API, resolver tracing is pretty simple: instrument each resolver function call, then package it up and ship it to Studio.</p>



<p>It’s harder in a federated graph. Apollo Gateway doesn’t execute resolvers. Instead, that happens within subgraph services on other machines. So Apollo invented “Inline Tracing”, where subgraphs trace their requests and send the data back to the gateway <em>inline</em> — as extensions on the response. The gateway then combines traces from all subgraph responses into a complete trace and sends it to Studio.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;data&quot;: {
    &quot;topProducts&quot;: [
      {
        &quot;title&quot;: &quot;Dune&quot;,
        &quot;author&quot;: &quot;Frank Herbert&quot;
      }
    ]
  },
  &quot;extensions&quot;: {
    &quot;ftv1&quot;: &quot;676f6f64206a6f6220696e7665737469676174696e67207468697320737472696e672120636f6d6520776f726b20666f72207573212068747470733a2f2f7777772e61706f6c6c6f6772617068716c2e636f6d2f63617265657273&quot;
  }
}</code></pre>



<p><em>The trace data is a base64-encoded protocol buffer message.</em></p>



<p>I was so excited to get this data that I ended up contributing the first ports of <em><code>ftv1</code></em> (”federated tracing version one”) to both <a rel="noreferrer noopener" href="https://github.com/Gusto/apollo-federation-ruby#tracing" target="_blank">graphql-ruby</a> and <a rel="noreferrer noopener" href="https://github.com/apollographql/federation-jvm#federated-tracing" target="_blank">federation-jvm</a> so I could see federated traces in the graphs I worked on at Square.</p>



<h2 class="wp-block-heading"><a href="#the-challenges-of-inline-tracing" aria-hidden="true" class="aal_anchor" id="the-challenges-of-inline-tracing"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The Challenges of Inline Tracing</h2>



<p>Apollo Federation allows you to build subgraphs in <a href="https://www.apollographql.com/docs/federation/other-servers/">many languages and platforms</a>, not just Ruby, Java, and Node. However, not all of the subgraph implementations support <code>ftv1</code> tracing yet, meaning that your choice of language could affect the availability of traces and field usage data.</p>



<p>On top of that, inline trace data adds overhead to subgraph requests. You may see a performance impact on the individual subgraph responses to the gateway.</p>



<p>Other systems like OpenTelemetry don’t use inline tracing. Instead, they send data out-of-band to external systems, which collate tracing data from multiple services.</p>



<p>Why doesn’t Inline Tracing work like OpenTelemetry? Because it’s a lot more work to set up a system of collector sidecars and exporter services! Inline Tracing is so easy to set up that it’s on by default—you can’t say that about most tracing systems!</p>



<p>However, the performance impact of inline tracing is unacceptable for some. This is especially true for GraphQL developers supporting very large requests. The size of the trace scales linearly with the size of the request (making the total response size grow super-linearly!)</p>



<p>Prior to Apollo Server 3.6, you had only two options to mitigate the performance impact.</p>



<ul class="wp-block-list"><li>Disabling inline tracing entirely. This avoids extra work during execution and avoids bloating the response payload. Unfortunately, it also removed both the trace data in Operations tab and the field usage data in the Fields page.</li><li>Sampling using <code>includeRequest</code>. This would affect <em>all</em> statistics reported to Studio, so you’ll lose accurate request counts, client usage data, and more.</li></ul>



<p>Given these downsides, we wanted to enhance Apollo Server’s performance while collecting as much useful data as we could. To achieve this goal, we built a new feature that uses static analysis for usage reporting.</p>



<h2 class="wp-block-heading"><a href="#usage-reporting-with-static-operation-analysis" aria-hidden="true" class="aal_anchor" id="usage-reporting-with-static-operation-analysis"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Usage reporting with static operation analysis</h2>



<p>With GraphQL, it’s critical to know which fields are referenced in operations, even if they’re never resolved. This data powers the breaking change detection in Apollo Studio’s <a href="https://www.apollographql.com/docs/studio/schema-checks/">Checks</a> feature and is the inspiration for this new usage reporting based on the static analysis of “operation shapes”.</p>



<p>Operation shape-based reporting doesn’t rely on tracing. Instead, it statically analyzes the operation document to count the types and fields. It’s much cheaper to run this algorithm over the document than it is to trace every single field resolver. And most importantly, we run this algorithm only in the gateway, avoiding the need to send tracing data between servers. This means we support detailed field usage information for all subgraph servers regardless of language or framework.</p>



<p>Usage reporting based on operation shape analysis is available in Apollo Server as of version 3.6, <a href="https://github.com/apollographql/apollo-server/blob/main/CHANGELOG.md#v360">released in December 2021</a>. The new field usage metrics improvements apply to monolithic graphs as well as federated graphs that use Apollo Gateway.</p>



<h2 class="wp-block-heading"><a href="#the-nuances-of-operation-shape-based-analysis" aria-hidden="true" class="aal_anchor" id="the-nuances-of-operation-shape-based-analysis"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The nuances of operation shape-based analysis</h2>



<p>Consider this operation:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query TopProducts {
  topProducts {
    title
    ... on Book {
      author
    }
    ... on Album {
      artist
    }
  }
}</code></pre>



<p>When you statically analyze this operation, you know that these fields are <em>referenced</em>:</p>



<ul class="wp-block-list"><li><code>Query.topProducts</code></li><li><code>Product.title</code> (the interface field!)</li><li><code>Book.author</code></li><li><code>Album.artist</code></li></ul>



<p>Notably, it’s not possible to know if <code>Book.title</code> or <code>Album.title</code> are used!</p>



<p>However, by tracing all the resolvers, you know exactly how many times a field is resolved. When <code>topProducts</code> returns the possible types of the <code>Product</code> interface, you’ll know which items are Books and which ones are Albums. This is how you can know the number of times the <code>Book.title</code> and <code>Album.title</code> fields are <em>executed</em>.</p>



<p>The difference between “field executions” (from tracing) and “referencing operations” (from operation shape-based usage reporting) is important. We decided to make this crystal clear by showing two different metrics for each field.</p>



<figure class="wp-block-image size-large"><img decoding="async" src="https://www.apollographql.com/docs/studio/cb24a5b0244106da154eb781a08c99c1/fields-page.jpg" alt=""/><figcaption>Screenshot of the Fields page with the new &#8220;Referencing Operations&#8221; column.</figcaption></figure>



<p>The Apollo Server <a href="https://www.apollographql.com/docs/studio/metrics/field-usage/">documentation</a> goes into even more detail about the differences between “Field Execution” and “Referencing Operations”.</p>



<p>If you disable Inline Tracing, you won’t get the data that powers the “Field executions” metric in the Fields page, but you’ll still see the “Referencing operations” metric.</p>



<h2 class="wp-block-heading"><a href="#trace-sampling" aria-hidden="true" class="aal_anchor" id="trace-sampling"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Trace Sampling</h2>



<p>Instead of disabling Inline Tracing, Apollo Server 3.6 also includes a new option, <code>fieldLevelInstrumentation</code>, that makes it super easy to enable Inline Tracing for a small percentage of requests:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">plugins: [
  ApolloServerPluginUsageReporting({
    fieldLevelInstrumentation: 0.01
  })
]</code></pre>



<p>With the above configuration, the gateway will enable <code>ftv1</code> tracing on subgraphs for 1% of requests. This means you’ll pay a performance penalty for a small subset of requests, but with enough traffic that 1% of requests will give you plenty of data to power the Operations tabs and help you find and diagnose issues in your resolvers.</p>



<p>Crucially, you will still get accurate metrics on field usage, overall operation latency, and error rates for 100% of requests.</p>



<p>The&nbsp;<code>includeRequest</code>&nbsp;option is still available but is no longer recommended for configuring tracing. It could still be useful if you want to exclude bot traffic from data in Studio with a configuration similar to:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">ApolloServerPluginUsageReporting({
  includeRequest({ request }) {
    // set by a security scanner at the ingress
    if (request.headers[&quot;X-PROBABLY-A-BOT&quot;]) {
      return false;
    }
    return true;
  }
})</code></pre>



<h2 class="wp-block-heading"><a href="#wrapping-up" aria-hidden="true" class="aal_anchor" id="wrapping-up"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Wrapping Up</h2>



<p>Apollo Server 3.6 is a big win for GraphQL and Federation. It directly addresses the limitations of Inline Tracing while still allowing you to capture a crystal-clear picture of graph usage and performance in Apollo Studio. And when combined with OpenTelemetry (<a href="https://www.apollographql.com/blog/backend/architecture/introducing-open-telemetry-for-apollo-federation/">as discussed previously</a>), you get an even more complete picture of your API&#8217;s performance across your entire stack.</p>



<p>Personally, I’ve enjoyed learning about the differences between field references and executions from <a href="https://www.apollographql.com/docs/studio/metrics/field-usage/">the great documentation we’ve put together on Field Usage</a>. It’s given me a whole new appreciation for GraphQL and graph usage data!</p>



<h3 class="wp-block-heading"><a href="#resources" aria-hidden="true" class="aal_anchor" id="resources"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Resources</h3>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/studio/metrics/field-usage/">Field Usage in Apollo Studio</a></li><li><a href="https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting/">Usage Reporting Plugin documentation</a></li><li><a href="https://www.apollographql.com/docs/federation/metrics/">Federated Tracing documentation</a></li><li><a href="https://www.apollographql.com/docs/federation/opentelemetry/">OpenTelemetry support in Apollo Gateway documentation</a></li></ul>



<p></p>


Faster federated graphs and better usage data with Apollo Server 3.6


<p>You may have heard about Apollo Federation before, especially if you&#8217;re on a team that uses GraphQL and Apollo tools. But what is it exactly?</p>



<p>Apollo Federation is an approach to application architecture created by Apollo. It’s open-sourced so anyone has access. It’s not a product that we offer but instead, it’s a specification or a standard for building a distributed graph. It can be implemented in any language that is compatible with GraphQL.</p>



<p>But what does that entail? Why was Apollo Federation created to begin with? These questions will be addressed in this blog post and we’ll also cover the benefits of using the Apollo Federation specification and how you can get started.</p>



<h3 class="wp-block-heading"><a href="#before-you-read" aria-hidden="true" class="aal_anchor" id="before-you-read"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Before you read&#8230;</strong></h3>



<p>Before you dive into this article, here are a few things you should know:</p>



<ul class="wp-block-list"><li>You know what GraphQL is. If you need help with this, check out this <a href="https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/">What is GraphQL</a> article</li><li>You have built a graph before. If you haven’t done this before or if you need a refresher, take a look at our <a href="https://odyssey.apollographql.com/" data-type="URL" data-id="https://odyssey.apollographql.com/">Odyssey course</a>. You can also follow our <a href="https://www.apollographql.com/docs/tutorial/introduction/">Full-stack GraphQL Tutorial</a>.</li></ul>



<p>If you have an understanding of these things, you’re ready to continue ahead with this article!</p>



<h2 class="wp-block-heading"><a href="#graphs-before-apollo-federation" aria-hidden="true" class="aal_anchor" id="graphs-before-apollo-federation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Graphs Before Apollo Federation</strong></h2>



<p>There is no doubt that GraphQL is great for building out complex data sets and APIs. But as a company, product, or project grows, so does your graph. And as your graph grows, you can develop a monolithic architecture and by that we mean you’ll end up with one huge graph. Monolithic architectures are great when we’re just starting out or when a project is fairly small in scope. But, if not organized correctly, a monolithic graph can present various problems that ultimately lead to slower development and unhappy developers.</p>



<p>With a monolithic graph, things can get messy and confusing quickly. With so much code in one place, monolithic graphs can be hard to navigate, especially for new developers who are onboarding or joining your team. It’s also difficult to keep monolithic graphs up to date without introducing any breaking changes. This becomes more and more problematic as your project or company needs grow and as you gain traffic.</p>



<p>These are problems that needed fixing. There were some solutions that were implemented. (One of them is <a href="https://www.apollographql.com/blog/backend/graphql-schema-stitching/">schema stitching</a>, which we won’t dive into too much here). But none of them truly solved these issues in a practical way. So we at Apollo took some time to create the Apollo Federation specification.</p>



<h2 class="wp-block-heading"><a href="#the-benefits-of-implementing-apollo-federation" aria-hidden="true" class="aal_anchor" id="the-benefits-of-implementing-apollo-federation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>The Benefits of Implementing Apollo Federation</strong></h2>



<p>As mentioned earlier, Apollo Federation is an open-source architecture created by Apollo. It was created to help you and/or your team organize and implement your graph as it grows and evolves along with your application. So how exactly does it do this?</p>



<p>Apollo Federation is built around a design principle called <a href="https://www.apollographql.com/docs/federation/#separation-of-concerns">separation of concerns</a>. Separation of concerns means that an application, codebase, or program is broken up into distinct sections, each section addressing a separate concern. How is this done with Apollo Federation?</p>



<p>With the Apollo Federation architecture, instead of having one large graph, you create a federated graph. This means your graph will be divided into smaller subgraphs. These subgraphs are usually broken up based on the function or purpose they fulfill in your application, team, or company. For example, if you or your team are building a restaurant review app, there would be a subgraph for reviews and a subgraph for locations.</p>



<p>This is what separation of concerns looks like and it’s super-useful. Apollo Federation makes it easier to modularize your code, keep things organized, and makes it easier for everyone to navigate your codebase.</p>



<p>If you’re working on a team, this also means that each team can have its own dedicated subgraph. So, returning to our previous example, the team that works on locations only has to deal with the locations subgraph. The team that works on reviews only has to deal with the reviews subgraph. This cuts down on breaking changes and communication while still maintaining necessary collaboration. Ultimately, this means that development will be smoother and quicker.</p>



<h3 class="wp-block-heading"><a href="#apollo-federation-and-client-side-teams" aria-hidden="true" class="aal_anchor" id="apollo-federation-and-client-side-teams"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Apollo Federation and Client-side Teams</h3>



<p>With all these subgraphs, does that mean that folks on the client-side will have to hit several endpoints to change or retrieve the data they need? Thankfully, this isn&#8217;t the case! Apollo federation makes sure that while improving the experience for developers working directly with the graph, client-side developers don’t need to change anything about the way they work.</p>



<h2 class="wp-block-heading"><a href="#federated-architecture" aria-hidden="true" class="aal_anchor" id="federated-architecture"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Federated architecture</h2>



<p>We know what the Apollo Federation standards are and how those can benefit individual developers and teams. But how is this architecture implemented? </p>



<p>An Apollo Federation architecture consists of the following components:</p>



<ul class="wp-block-list"><li>A <strong>collection of subgraphs</strong> (usually represented by different back-end services) that each define a distinct GraphQL schema</li><li>A <strong>gateway</strong> that uses a <strong>supergraph</strong> schema to execute queries across multiple subgraphs. The gateway creates the supergraph by combining the subgraph schemas together and serves only the supergraph schema to clients.</li></ul>



<h2 class="wp-block-heading"><a href="#to-sum-it-up-heres-what-apollo-federation-can-do-for-you" aria-hidden="true" class="aal_anchor" id="to-sum-it-up-heres-what-apollo-federation-can-do-for-you"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>To sum it up, here’s what Apollo Federation can do for you</h2>



<p>The Apollo Federation architecture is great for everyone.</p>



<ul class="wp-block-list"><li>For individual/solo developers: modularizing your graph means your code will be more organized, easier to navigate, and easier to scale.</li><li>For teams: with the separation of concerns principle, each team can deal with their own subgraph which ultimately increases team productivity and collaboration.</li><li>For client-side developers: their work is basically unchanged so they still get the benefits of using GraphQL aka only accessing one endpoint and only dealing with the schema.</li></ul>



<h2 class="wp-block-heading"><a href="#getting-started-with-apollo-federation" aria-hidden="true" class="aal_anchor" id="getting-started-with-apollo-federation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Getting Started with Apollo Federation</strong></h2>



<p>After reading this, you might be thinking that Apollo Federation is something you want to try for yourself or your team. There are a few places that will help you learn more about Apollo Federation and get started with implementing it. Check out the <a href="https://www.apollographql.com/docs/federation/federation-spec/">Apollo Federation specification</a> for more info on the principles behind the architecture. We also have a <a href="https://www.apollographql.com/docs/federation/quickstart/">Federation quickstart</a> that can get you up and running with a step-by-step guide.</p>


What Is Apollo Federation?

Apollo Router: our GraphQL Federation runtime in Rust


<p><em>🚀 🎉  Heads up &#8211; Federation 2 and Gateway 2.x are now GA! Check out the <a href="https://www.apollographql.com/blog/apollo-federation-2-is-now-generally-available/" data-type="URL" data-id="https://www.apollographql.com/blog/apollo-federation-2-is-now-generally-available/">GA announcement blog</a> or head over to the <a href="https://www.apollographql.com/docs/federation/" data-type="URL" data-id="https://www.apollographql.com/docs/federation/">Federation docs</a> to get started.</em></p>



<hr class="wp-block-separator"/>



<p>It&#8217;s been amazing to see the momentum grow around Apollo Federation with over 1M weekly downloads and 12K+ projects using Apollo Federation. Thanks to community contributions, the thriving ecosystem around Apollo Federation means you can federate subgraphs written in <a href="https://www.apollographql.com/docs/federation/other-servers/">over 12 languages</a> and frameworks.</p>



<p>Originally <a href="https://www.apollographql.com/blog/announcement/apollo-federation-f260cf525d21/">released in 2019</a>, Federation powers some of the largest graphs in the world, including <a href="https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-2-bbe71aaec44a">Netflix</a>, <a href="https://medium.com/walmartglobaltech/federated-graphql-walmart-bfc85c2553de">Walmart</a>, <a href="https://engineering.ziffmedia.com/retailmenot-graphql-federation-3bb36dac5aaa">RetailMeNot</a>, and <a href="https://medium.com/paypal-tech/graphql-at-paypal-an-adoption-story-b7e01175f2b7">PayPal</a>. Developers are choosing Apollo Federation because it’s a proven approach for rapidly scaling a graph across multiple teams.</p>



<p>Today, we’re excited to celebrate the next major milestone: Apollo Federation 2. The new version builds on the success of the original with an improved shared ownership model, enhanced type merging, and cleaner syntax for a smoother developer experience. It’s backwards compatible, requiring no major changes to your subgraphs. <a href="https://www.apollographql.com/docs/federation/v2/quickstart/">Try the alpha today!</a> 🚀</p>



<h2 class="wp-block-heading"><a href="#apollo-federation-2" aria-hidden="true" class="aal_anchor" id="apollo-federation-2"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Apollo Federation 2</h2>



<p>Apollo Federation is an architecture for declaratively composing subgraphs into a unified graph. Each team can own their slice of the graph independently, empowering them to deliver autonomously and incrementally.</p>



<p>Designed in collaboration with the GraphQL community, Federation 2 is a clean-sheet implementation of the core composition and query-planning engine at the heart of Apollo Federation. We’ve improved the developer experience by adding deeper static analysis, cleaner error messages, and new composition hints that help you catch errors sooner and understand how your schema impacts performance. With the new version, we’ve streamlined common tasks like extending a type and simplified advanced workflows like migrating a field across subgraphs with no downtime.</p>



<p>Following in the footsteps of modern infrastructure projects like Elasticsearch and MongoDB, <a href="https://www.apollographql.com/blog/announcement/moving-apollo-federation-2-to-the-elastic-license-v2">we’re moving Federation 2 to the Elastic License v2</a> &#8212; an open and&nbsp;permissive license with few restrictions. This change shouldn’t affect the vast majority of our community, and the new code is still free to use and modify. Subgraph packages will remain MIT, as well as the 0.x Federation packages, so there are no changes to what you’re doing today.</p>



<h3 class="wp-block-heading"><a href="#build-with-any-natural-graphql-schema" aria-hidden="true" class="aal_anchor" id="build-with-any-natural-graphql-schema"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Build with any natural GraphQL schema</h3>



<p>Federation 2 adds first-class support for shared interfaces, enums, and other value types. Common tasks like extending a federated type or denormalizing a field for better performance are now possible without special directives and keywords.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="405" src="https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-1024x405.png" alt="" class="wp-image-10646" srcset="https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-1024x405.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-300x119.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-768x304.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-1536x607.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-2048x810.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-1200x474.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-21-natural-graphql-1980x783.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<h3 class="wp-block-heading"><a href="#deliver-smaller-increments-with-better-shared-types" aria-hidden="true" class="aal_anchor" id="deliver-smaller-increments-with-better-shared-types"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Deliver smaller increments with better shared types</h3>



<p>Apollo Federation already supports a shared ownership model that lets you spread a federated type across subgraphs to distribute its implementation. You can reuse common value types like interfaces and enums. However, there are restrictions on how shared types can be defined and evolved. As a result, teams may find themselves stuck when making changes to shared types until all subgraphs are able to deliver a coordinated change in lockstep.</p>



<p>Federation 2 removes these restrictions with an improved shared ownership model and enhanced type merging that enables teams to deliver smaller incremental changes with a cleaner separation of concerns.</p>



<p><strong>Flexible value type merging </strong>is now supported, so value types don’t need to be identical across subgraphs. Value type definitions are now merged into a single unified type, much like type merging support for federated types today. Smaller incremental changes, like adding a field, can often be rolled out one subgraph at a time.</p>



<p><strong>Federated types have improved shared ownership,</strong> which means fields can now exist in multiple subgraphs simultaneously. This paves the way for natively supported field migrations with an asynchronous transfer of ownership from one subgraph to another with no downtime or tight release coordination.</p>



<h3 class="wp-block-heading"><a href="#catch-errors-sooner-with-improved-static-analysis" aria-hidden="true" class="aal_anchor" id="catch-errors-sooner-with-improved-static-analysis"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Catch errors sooner with improved static analysis</h3>



<p>Federation 2 has deeper static analysis, better error messages and a new generalized composition model that helps you catch more errors at build-time instead of at runtime. The rewritten composition engine now validates all theoretically possible queries and provides more descriptive error messages when a query can’t be satisfied.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="484" src="https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-1024x484.png" alt="" class="wp-image-10612" srcset="https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-1024x484.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-300x142.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-768x363.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-1536x726.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-2048x968.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-1200x567.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/11/image-19-deeper-validation-1980x936.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>New composition hints help you understand how schema definitions influence query planning and performance. We’ve integrated them into the <a href="https://www.apollographql.com/blog/announcement/tooling/powerful-new-graphql-tools-for-apollo-federation/">powerful tools for Apollo Federation</a>:</p>



<ul class="wp-block-list"><li><a href="https://marketplace.visualstudio.com/items?itemName=apollographql.apollo-workbench">Apollo Workbench</a> shows composition hints in the problems tray with new hover tips.&nbsp;</li><li><a href="https://www.apollographql.com/docs/rover/">Rover</a> includes composition hints in both standard and structured JSON output so you can integrate them with other tools in your pipeline.</li><li><a href="https://www.apollographql.com/docs/studio/">Apollo Studio</a> uses composition hints to help you ensure design guidelines and best practices.</li></ul>



<p>While Federation 2 is<a href="https://www.apollographql.com/docs/federation/v2/federation-2/backward-compatibility/"> backwards compatible</a>, its enhanced validation might catch a few things that the original Federation didn&#8217;t. Things you&#8217;ll be happy to know about!</p>



<h2 class="wp-block-heading"><a href="#quick-tour-of-federation-2" aria-hidden="true" class="aal_anchor" id="quick-tour-of-federation-2"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Quick tour of Federation 2</h2>



<p>We’ve prepared this video to highlight some key improvements in Federation 2, including Apollo Workbench support for composition hints. You’ll also learn how to compose and run a graph with Federation 2 using the v2 gateway and Apollo Studio.</p>



<figure class="wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="Apollo Federation 2: Preview Demo with Apollo Studio and Workbench" width="580" height="326" src="https://www.youtube.com/embed/WcHYa39bUk8?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



<h2 class="wp-block-heading"><a href="#getting-started" aria-hidden="true" class="aal_anchor" id="getting-started"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Getting started</h2>



<p>We’d love your early feedback on the initial alpha release!</p>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/federation/v2">Read the docs</a></li><li><a href="https://www.apollographql.com/docs/federation/v2/quickstart/">Try it out</a></li><li><a href="https://community.apollographql.com/t/announcing-apollo-federation-2/1821">Let us know what you think!</a></li></ul>



<h2 class="wp-block-heading"><a href="#whats-next" aria-hidden="true" class="aal_anchor" id="whats-next"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What’s next?</h2>



<p>There’s a lot we’re adding in the coming months:</p>



<ul class="wp-block-list"><li>New directives that support a stronger source of truth, field migration across subgraphs, and type merging that can be relaxed even further.</li><li>Expanded use of <a href="https://specs.apollo.dev/core/v0.2">core schemas</a> to compose your own directives in subgraphs and process supergraph schemas with a new <a href="https://github.com/apollographql/core-schema-js">core-schema-js</a> library.</li><li>Harmonizing shared value types across subgraphs to steward core common types to a desired state.</li><li>Importing shared types into subgraph schemas, to keep things more DRY.</li><li>Advanced caching, auth, demand control, rate limiting, governance, and more!</li></ul>



<h2 class="wp-block-heading"><a href="#learn-more-at-graphql-summit" aria-hidden="true" class="aal_anchor" id="learn-more-at-graphql-summit"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Learn more at GraphQL Summit</h2>



<p>See Federation 2 in action at GraphQL Summit on November 10th and 11th, 2021.&nbsp;</p>



<p><a href="https://summit.graphql.com/#register">Register for free</a> and join us for the keynote and a deep dive session on “The Future of Apollo Federation.” We’ll discuss and demo Federation 2, designed in collaboration with Netflix, to make it even easier to build, use and scale your graph!</p>



<h2 class="wp-block-heading"><a href="#get-involved" aria-hidden="true" class="aal_anchor" id="get-involved"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Get involved!</h2>



<ul class="wp-block-list"><li><a href="https://github.com/apollographql/federation">GitHub</a></li><li><a href="https://community.apollographql.com/">Apollo Community Forum</a></li><li><a href="https://community.apollographql.com/t/apollo-federation-subgraph-library-maintainer-support/1112">Subgraph Library Maintainer Support</a></li></ul>


Announcing Apollo Federation 2


<p>I&#8217;ve been helping companies develop their graph using Apollo Federation for over two years now, and it&#8217;s amazing to see all the different applications they&#8217;ve enabled. </p>



<p>In developing one graph, companies often struggle to define a process for effectively governing changes to the federated schema. Some companies use a Google doc, while others use a blank piece of paper to plan out a new schema change. Regardless, there is always <em>some</em> medium used as a &#8220;template&#8221; for the desired governance process. In my experience, these primitive mediums always come with unnecessary challenges, whether it&#8217;s an electronic document that doesn&#8217;t have the context to the subgraph schemas or a monorepo that requires starting up all other services to plan a schema change.</p>



<p>We need a better way to design schema changes in a federated GraphQL architecture — one where we can <strong>understand our graphs composition at design time instead of the implementation phase</strong>. You shouldn&#8217;t have to write any code when planning a schema design; you should change be able to change the schema directly.</p>



<p>For this reason, we built Apollo Workbench: a better way to design your federated graph — whether you have an existing graph (monolith, BFF, schema stitched), you&#8217;re migrating to Apollo Federation, or you&#8217;re just getting started.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="576" src="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM-1024x576.png" alt="" class="wp-image-8078" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM-1024x576.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM-300x169.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM-768x432.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM-1536x864.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM-1200x675.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-19-at-10.23.50-AM.png 1920w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Apollo Workbench is a tool built from experience working with our customers as they needed help designing their graphs. It dramatically reduces the feedback loop time when planning our changes to your graph. Specifically, Workbench helps you build faster with:</p>



<ul class="wp-block-list"><li>Composition Errors &#8211; For checking your design as you go</li><li>Query Explain &#8211; Understanding how a query will execute based on its generated query plan</li><li>Mocking your designs &#8211; This considerably improves the DX for client developers by enabling them to build directly against a locally mocked federated graph in development instead of having to spin up all the backing services or point to a production endpoint</li></ul>



<p>Let’s take a closer look at each.</p>



<h2 class="wp-block-heading"><a href="#composition-errors-checking-your-design" aria-hidden="true" class="aal_anchor" id="composition-errors-checking-your-design"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Composition Errors &#8211; Checking your design</h2>



<p>While working with companies on building their graph, the most common problem I saw was teams designing a schema change that led to some composition errors. After planning the design change in some electronic document, everyone would agree on the changes so the work would begin. Teams would implement the changes, but when the developer starts up the <code>ApolloGateway</code> instance, it wouldn&#8217;t be uncommon to find that it doesn&#8217;t start and that it has composition errors:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="310" src="https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-1024x310.png" alt="carbon (3).png" class="wp-image-8062" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-1024x310.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-300x91.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-768x233.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-1536x465.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-1200x363.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-3-1980x599.png 1980w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-3.png 2048w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Other teams plan their design changes around a monorepo structure. The benefit here is that they could merely start everything and understand composition errors upfront, thereby improving the feedback loop. The challenge here arises when creating a new subgraph with a lot of <em>copypasta</em> throughout the project.</p>



<p>Today, Apollo Workbench enables you to work with your subgraph schemas directly, with any composition errors displayed prominently in the VS Code Problems Panel:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="575" src="https://wp.apollographql.com/wp-content/uploads/2021/07/image-4-1024x575.png" alt="Screen Shot 2021-07-14 at 9.51.01 AM.png" class="wp-image-8064" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/image-4-1024x575.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-4-300x169.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-4-768x432.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-4-1200x674.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-4.png 1276w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>This is great because now we can understand our design&#8217;s overall composition without starting anything up or writing any code. It also enables more people to be involved in the process since you&#8217;re just working with the schema directly. There is also IntelliSense for a composed graph where available types to extend are displayed (along with the owning service).</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="575" src="https://wp.apollographql.com/wp-content/uploads/2021/07/image-5-1024x575.png" alt="Screen Shot 2021-07-14 at 10.21.08 AM.png" class="wp-image-8066" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/image-5-1024x575.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-5-300x169.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-5-768x432.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-5-1200x674.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-5.png 1276w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Suppose you&#8217;re using Apollo Studio and have integrated with the schema registry using Rover. In that case, you can log in to Apollo Workbench with <a href="https://studio.apollographql.com/user-settings">your user API key from your Personal Settings in Apollo Studio</a>. Then you can create designs from your graphs in Apollo Studio:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1920" height="1000" src="https://wp.apollographql.com/wp-content/uploads/2021/07/out-2.gif" alt="Logging into workbench" class="wp-image-8087"/></figure>



<h2 class="wp-block-heading"><a href="#query-explain" aria-hidden="true" class="aal_anchor" id="query-explain"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Query <code>EXPLAIN</code></h2>



<p>One of Apollo Federation&#8217;s significant benefits is understanding precisely how any given GraphQL operation will execute across your graph. This understanding comes in the form of a query plan generated for each unique operation. I like to think of the query plan as <code>EXPLAIN</code> for GraphQL queries. As teams design changes to their graph, they may need to contextualize a change to a GraphQL operation; this could be from a new set of functionality or a schema change that impacts operations currently running in Production.</p>



<p>With Apollo Workbench, you can add an operation to any design and view the query plan for any composing design:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1920" height="1000" src="https://wp.apollographql.com/wp-content/uploads/2021/07/out-3.gif" alt="" class="wp-image-8089"/></figure>



<p>Query <code>EXPLAIN</code> provides us with instant feedback on how a design might impact some existing operations. We all want performant queries, right? When you&#8217;re tweaking a design, it&#8217;s a great idea to start by looking at the query plan first and understanding how it changes with the tweaks you make.</p>



<p>If you&#8217;re using Apollo Studio and logged into Apollo Workbench, you can also click on a graph to load the operations from that graph variant. Then you can pull that operation into your design and see how it would execute:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1920" height="1000" src="https://wp.apollographql.com/wp-content/uploads/2021/07/out-4.gif" alt="Apollo Workbench Operations with Apollo Studio" class="wp-image-8095"/></figure>



<h2 class="wp-block-heading"><a href="#mocking-your-design" aria-hidden="true" class="aal_anchor" id="mocking-your-design"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Mocking your design</h2>



<p>Once you&#8217;ve created a design and you&#8217;re ready for the next steps, what do you do? A lot of companies explore some strategies around mocking to enable teams to develop independently. Client teams typically have some tooling to generate types, and they&#8217;ll want to do that for the new schema without waiting for the server team to spin something up. Apollo Workbench provides a simple mocking engine that will generate a mocked graph for any design you create.</p>



<p>Press the play button, and a mocked server will run locally for each subgraph and the graph router (<code>ApolloGateway</code> instance). The router will default to port <code>4000</code>, and the subgraphs will start by default on port <code>4001</code> and increment from there:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1920" height="1000" src="https://wp.apollographql.com/wp-content/uploads/2021/07/out-5.gif" alt="Apollo Workbench Mocks" class="wp-image-8097"/></figure>



<p><em>Hint: there are settings available in the extension to change what port you want the mocks to run on:</em></p>



<pre class="wp-block-code"><code>&quot;apollo-workbench.gatewayPort&quot;: 5000,&lt;br&gt;&quot;apollo-workbench.startingServerPort&quot;: 5001</code></pre>



<p>With Apollo Workbench, anyone can run a design with mocked data locally. The extension also has <code>faker</code> integrated into it, and you can write your own custom mocks:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="641" src="https://wp.apollographql.com/wp-content/uploads/2021/07/image-10-1024x641.png" alt="Apollo Workbench Custom Mocks" class="wp-image-8076" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/image-10-1024x641.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-10-300x188.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-10-768x481.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-10-1200x751.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-10.png 1276w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p><em>Note: a workbench file contains everything in the design, including the code snippet for your custom mocks. <code>eval</code> is used for the <code>JavaScript</code> that you write and a project is managed in the extensions global storage which provides you with feedback if you have errors.</em><br><br>Now you have all the tools you need to plan your graph designs with a complete understanding of what will execute without any code. Apollo Workbench provides insight into the graph and enables you to work only with the subgraph schemas to understand extension points, composition errors, and query execution plans. Once you’re complete with a design, you can mock it locally and use <a href="https://studio.apollographql.com/sandbox/explorer">Apollo Sandbox</a> to explore your graph.</p>



<h2 class="wp-block-heading"><a href="#getting-started" aria-hidden="true" class="aal_anchor" id="getting-started"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Getting started</h2>



<p>To get started with Apollo Workbench for your next graph design, <a href="https://apollographql.github.io/apollo-workbench-vscode/">check out the official docs for installation instructions.</a></p>



<p>Workbench works best when you can design all your changes from one centralized schema registry. If you haven’t already, I recommend you <a href="https://studio.apollographql.com/signup">sign up for an account with Apollo Studio</a> and <a href="https://www.apollographql.com/docs/studio/schema/cli-registration/">push your subgraph schemas into the registry</a> with Rover. Oh yeah and don’t forget, the schema registry is free on our community tier forever.</p>



<p>Happy coding!</p>


Apollo Workbench: A Better Way to Design Federated Graphs


<p>One of the very best ways to improve your product is to use it yourself. We&#8217;ve been using Apollo Client and Server libraries internally at Apollo for ages. Still, it wasn&#8217;t until we released <a href="https://odyssey.apollographql.com/">Odyssey</a> (the Apollo learning platform) that we realized we had the perfect opportunity to use Apollo Federation to consolidate our efforts with Apollo Studio.<br><br>In this article, we&#8217;ll learn about what Federation is, walk you through our use case for Odyssey, show you how we set it up, challenges we overcame, and ultimately why Federation was a great solution.</p>



<h2 class="wp-block-heading"><a href="#first-what-is-apollo-federation" aria-hidden="true" class="aal_anchor" id="first-what-is-apollo-federation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>First, what is Apollo Federation?</h2>



<p><a href="https://www.apollographql.com/docs/federation/">Apollo Federation</a> enables you to divide a single GraphQL API’s implementation across multiple back-end services. Each service has a different GraphQL schema that represents a different part of the combined API:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="419" src="https://wp.apollographql.com/wp-content/uploads/2021/07/image-1024x419.png" alt="Screen Shot 2021-04-15 at 11.31.35 AM.png" class="wp-image-7931" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/image-1024x419.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-300x123.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-768x314.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/image.png 1070w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>A <strong>gateway</strong> is responsible for receiving incoming queries and splitting them up across whichever services are required to resolve them. The gateway then takes each service’s response and combines them into a <em>single</em> response that’s returned to the querying client. From the client’s perspective, this works exactly like querying a <em>non</em>-federated API.</p>



<p>In addition to providing a clean API surface area, federation helps you control back-end data access. Each service only needs access to data stores related to its part of your API, and services don’t even need to be able to communicate with each other!</p>



<h2 class="wp-block-heading"><a href="#why-adopt-federation-for-odyssey" aria-hidden="true" class="aal_anchor" id="why-adopt-federation-for-odyssey"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Why adopt federation for Odyssey?</h2>



<p>While designing Odyssey, we knew we wanted to persist users’ progress through courses to provide a better learning experience. We wanted to associate this progress with the <code>User</code> type from <a href="https://studio.apollographql.com/">Apollo Studio</a>’s GraphQL API, which we were already using for authentication.</p>



<p>But it didn’t make sense for a user’s progress to be stored in Apollo Studio’s database—it should be stored in the Odyssey service! That way, our team could maintain and evolve our implementation without impacting or relying on the Studio team. Enter federation.</p>



<p>In Odyssey, we read user data from Studio’s Explorer API for authentication, and then use that information to fetch the correct data from our separate progression tracking service. Even though both services are federated with the same gateway, restrictions are set up so that Odyssey can’t request anything and everything from Studio or make any modifications to its database.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="419" src="https://wp.apollographql.com/wp-content/uploads/2021/07/image-1024x419.png" alt="Screen Shot 2021-06-16 at 12.38.07 PM.png" class="wp-image-7930" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/image-1024x419.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-300x123.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/image-768x314.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/image.png 1070w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>This implementation gives us a <strong>separation of concerns</strong> that enables different teams to work on different products and features without interfering with each other. In this way, we can read the user data from the Studio subgraph to help us grab the right data from our Odyssey progression subgraph instead of storing duplicate user info.</p>



<h2 class="wp-block-heading"><a href="#setting-up-federation" aria-hidden="true" class="aal_anchor" id="setting-up-federation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setting up federation</h2>



<p>Having never worked with federation before, the engineers on the Education team jumped into the docs. We created a local PostgreSQL database for progress tracking and built out our GraphQL server with Apollo Server.</p>



<p>Creating a federated service was surprisingly straightforward! To support <a href="https://www.apollographql.com/docs/federation/managed-federation/overview/">managed federation</a>, we saved our schema in a separate <code>.graphql</code> file. We created a federated schema by invoking <code>buildFederatedSchema</code> (imported from <code>@apollo/federation</code>) and passing in an array with an object containing our <code>typeDefs</code> and <code>resolvers</code>. The <code>typeDefs</code> were created by reading in our <code>schema.graphql</code> and wrapping it in a <code>gql</code> tag. Then we passed this federated schema as the value of the <code>schema</code> config option for our instance of <code>ApolloServer</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import {buildFederatedSchema} from &#039;@apollo/federation&#039;;
import {ApolloServer, gql} from &#039;apollo-server&#039;;
import {readFileSync} from &#039;fs&#039;;
import {resolvers} from &#039;./resolvers&#039;;

const schema = readFileSync(&#039;schema.graphql&#039;).toString();

const federatedSchema = buildFederatedSchema([
  {
    typeDefs: gql`${schema}`,
    resolvers
  }
]);

const server = new ApolloServer({
  schema: federatedSchema
})

server.listen({port: process.env.PORT}).then(({url}) =&gt; {
    console.log(`🚀 Server is listening on ${url}`);
});</code></pre>



<p>In order for our Odyssey subgraph to extend the User type, we submitted a PR to the Studio subgraph that added a <code>@key</code> directive to the User type definition. This created an <a href="https://www.apollographql.com/docs/federation/entities/">entity</a> that could be shared between subgraphs.</p>



<blockquote class="wp-block-quote has-text-align-left is-layout-flow wp-block-quote-is-layout-flow"><p>In Apollo Federation, an <strong>entity</strong> is an object type that you define canonically in <em>one</em> subgraph and can then reference and extend in <em>other</em> subgraphs. Entities are the core building block of a federated graph.</p></blockquote>



<p>In this case, we used the <code>id</code> field as the primary key by which the Odyssey subgraph would tell the Studio subgraph which user data we wanted.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">// example User type in Studio subgraph
type User @key(fields: &quot;id&quot;) {
  id: ID!
  name: String!
}</code></pre>



<p>Within the Odyssey subgraph, we created a <code>Task</code> type and extended the <code>User</code> from the Studio subgraph to add a <code>tasks</code> field that resolves to an array of <code>Task</code>s.</p>



<p>To extend the <code>User</code> type, we added a <code>@key</code> directive that matches the one on the <code>User</code> type in the Studio subgraph (see above example). The <code>id</code> field must be included since it’s part of the specified <code>@key</code>. It also has to be annotated with the <code>@external</code> directive to indicate that the field originates in the Studio subgraph.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">// example extended User in Odyssey subgraph schema
type Task {
  id: ID!
  value: String
  completedAt: Timestamp
}

extend type User @key(fields: &quot;id&quot;) {
  id: ID! @external
  tasks: [Task!]!
}</code></pre>



<p>Then we wrote a resolver for the <code>User.tasks</code> field that finds all tasks that belong to a given user.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// example resolver for an Odyssey user&#039;s tasks (in Odyssey subgraph)
{
  User: {
    tasks: user =&gt;
      Task.findAll({
        where: {
          userId: user.id
        }
      })
  }
}</code></pre>



<p>And finally, since we were tapping into the existing <a href="https://www.apollographql.com/docs/federation/gateway/">gateway</a> at Apollo, we didn’t need to worry about creating one. To work on our federated service locally, we added our service’s local endpoint to the locally-running gateway’s <code>serviceList</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// example gateway config
import { ApolloGateway } from &#039;@apollo/gateway&#039;;

const gateway = new ApolloGateway({
  serviceList: [
    { name: &#039;odyssey&#039;, url: &#039;http://localhost:4001&#039; },
    // Define additional services here
  ],
});</code></pre>



<h2 class="wp-block-heading"><a href="#challenges" aria-hidden="true" class="aal_anchor" id="challenges"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Challenges</h2>



<p>With everything set up, we wanted to test it all locally before deploying anything to make sure everything worked as expected. The biggest challenge we faced while creating our federated service was navigating other subgraph and gateway codebases and figuring out how to run them locally. While not specific to Apollo Federation, stepping into unfamiliar tools and codebases is a challenge that teams can expect to face when implementing federation themselves. Pair programming sessions with engineers from those teams proved invaluable in our development process.</p>



<p>With our server up and running locally, it was time to test out some queries! But we had a problem. We just wanted to check to see if everything was set up correctly and working as expected without also spinning up another server locally for the Studio Explorer API. How could we run a query that needs to get the <code>User</code> data from a service that we’re not running locally?</p>



<p>We learned that you can run an <code>_entities</code> query to effectively stub the response for the fields that rely on the service you aren’t running.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">query ($_representations: [_Any!]!) {
  _entities(representations: $_representations) {
    ... on User {
      tasks {
        id
        value
        completedAt
      }
    }
  }
}


// query variables
{
  &quot;_representations&quot;: [
    {
      &quot;__typename&quot;: &quot;User&quot;,
      &quot;id&quot;: &quot;1&quot;
    }
  ]
}</code></pre>



<p>You can read more in-depth about resolving requests for entities in the <a href="https://www.apollographql.com/docs/federation/federation-spec/#resolve-requests-for-entities">federation spec</a>.</p>



<h2 class="wp-block-heading"><a href="#benefits-of-our-federated-graph" aria-hidden="true" class="aal_anchor" id="benefits-of-our-federated-graph"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Benefits of our Federated graph</h2>



<p>With our service up and running, let’s take a look at some of the benefits we got out of our federated graph:</p>



<ul class="wp-block-list"><li>Having a separation of concerns with user data in one subgraph and task data in another reduced duplication of information. There’s no need to store the same user information in the Odyssey subgraph when it already exists in the Studio one.</li><li>We can make changes to the Odyssey subgraph without having to worry about impacting the Studio subgraph since they’re independent of one another. If we have some downtime, it won’t cause any downtime for the Studio team. Each team is responsible only for the data that they need to use.</li><li>We still only have one data graph to which we make requests! This helps clean up our frontend code by only needing to send requests to one source (the federated gateway) instead of two (one to the Studio graph and one to Odyssey).</li></ul>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>Coming into this project with no prior experience working with Apollo Federation, we found it surprisingly straightforward to configure our server and connect our service to the gateway. We had the opportunity to dig into another codebase and do some cross-team collaboration to get everything properly set up and deployed with how Apollo does things internally (these aren’t federation-specific steps, but were still part of our journey in creating our backend service). And we found some resources to help us in our local development that we can now use to improve Apollo’s own learning resources.</p>



<p>Now we’re excited to continue building and expanding our federated graph!</p>


Federation in Odyssey

Using Subscriptions with Your Federated Data Graph


<p>Caching, along with naming variables and off-by-one errors, is one of the hardest problems in programming. In this post, we’ll explore caching in a federated GraphQL context from local caching and memoization to distributed caching.&nbsp;</p>



<p>The approaches described here are only one of many ways to cache in a federated GraphQL architecture.&nbsp;</p>



<p>You can find the code describing each strategy <a href="https://github.com/kschrade/blog-post-support/tree/main/caching-and-federations">here</a>.</p>



<h2 class="wp-block-heading"><a href="#no-caching-a-basic-federated-architecture" aria-hidden="true" class="aal_anchor" id="no-caching-a-basic-federated-architecture"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>No caching: a basic federated architecture</strong></h2>



<p>Every good journey has a starting point; ours is a basic architecture with:</p>



<ul class="wp-block-list"><li>a GraphQL gateway (to consume requests)</li><li>an implementing service (where we define the resolvers)</li><li>and a backend service (to actually retrieve the data for the implementing service)</li></ul>



<p><img loading="lazy" decoding="async" width="358" height="400" src="https://lh6.googleusercontent.com/AauDSMUlIlFc2tSKinA85C7jLnfh9E4XI0QtDWnBs6pLSfAYm-ZQle-yLTTB-uhLrjb3FoIZjxH9TEf-ZQor0ryaIU9c9iB73XjoSTHpMDBMoAt7iWadP4jPupAGO0h3Btu6T52T"></p>



<p>Since we only have one <em>implementing service</em> at this time, every time a request comes into the gateway, it passes the request to the implementing service to resolve the data from the backend service.&nbsp;</p>



<p>There’s no caching here yet, and you can see an example of this basic <em>no-caching </em>architecture <a href="https://github.com/kschrade/blog-post-support/tree/main/caching-and-federations/no-cache">here</a>.</p>



<h2 class="wp-block-heading"><a href="#local-caching" aria-hidden="true" class="aal_anchor" id="local-caching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Local caching</strong></h2>



<p>Looking at the previous architecture above, you might notice that there’s a one-to-one ratio of requests that come into the gateway and hit the underlying backend service.&nbsp;</p>



<p>If we wanted to reduce strain on the backend service, we could introduce a cache, preventing the need to fetch data that has already been fetched by the implementing service.&nbsp;</p>



<p>A trivial approach is to introduce a <strong>local in-memory cache</strong> and cache against the API calls that our implementing service makes to the backend service Adjusting the architecture a little bit, our diagram now looks like:</p>



<p><img loading="lazy" decoding="async" width="505" height="565" src="https://lh3.googleusercontent.com/O3LvbVHWRwYBkd9qkdRB_uSgU9HooS-5FDn6ujgRw1PuoL36kfJBZVnWpSl6jme83wdvv0Cj21IuzZ_XWdUXthYBDZY51AxoTkFcvrYcWl1_7b0mPgfWGOaUeUOBBCE_UlMXKjrD"></p>



<p>Visit <a href="https://github.com/kschrade/blog-post-support/tree/main/caching-and-federations/local-cache">the GitHub repo for this post</a> to find an example of the <strong>local caching strategy</strong>.</p>



<h3 class="wp-block-heading"><a href="#memoization" aria-hidden="true" class="aal_anchor" id="memoization"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Memoization</strong></h3>



<p>When we talk about caching, in most cases, we are talking about <em>memorization</em>. Per <a href="https://www.definitions.net/">definitions.net</a>, memoization is:&nbsp;</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>&#8220;an optimization technique used primarily to speed up computer programs by having function calls avoid repeating the calculation of results for previously processed inputs.&#8221;&nbsp;</p></blockquote>



<p>Memoization helps us reduce the need to re-run operations that we’ve already performed. If the <em>parameters </em>to a function are exactly the same, then chances are &#8212; the output is going to be the same too! This is what our local caching approach is built upon.</p>



<p>For example, if we know that executing <code>getUser(id:1)</code> fetches the user with ID = 1, and running it with the exact same parameter will return the same result, we can just <em>save the result</em>, and instead of invoking the request all over again, we can just return the result!</p>



<p>Maybe you can see how useful this is for caching an API call, specifically. The approach to memoizing API calls leads to a lot cleaner code than if we had to cache a variety of search functions.&nbsp;</p>



<p>Here’s the memoization code we could use.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const memoization = (innerFn, getKeyFn, cache) =&gt; async (...args) =&gt; {
 const key = getKeyFn(args);
 
 try {
   const cacheVal = await cache.get(key);
   if (cacheVal) {
     return cacheVal;
   }
 } catch (e) {
   console.log(e);
 }
 
 const res = await innerFn(args);
 
 try {
   await cache.set(key, res);
 } catch (e) {
   console.log(e);
 }
 
 return res;
};
</code></pre>



<p>Let&#8217;s break down what’s happening above.</p>



<p>We have a function that takes in an `innerFn`, `getKeyFn`, and a `cache`.&nbsp;</p>



<p>The` innerFn` is the function you are trying to memorize and the get key function is used to create a cache key based on the arguments used to execute the function.&nbsp;</p>



<p>The memoization function uses the arguments of the `innerFn` (the function you are memoizing), creates a cache key, checks the cache for a value at that key and returns it if there’s a cache hit (meaning &#8211; the item was found).&nbsp;</p>



<p>If there’s a cache miss (the item wasn’t found), it executes the `innerFn`, waits for the result of the `innerFn`, caches that value using the key created by the parameters, and finally, returns the result at the end.&nbsp;&nbsp;You can find the entire implementation of this function <a href="https://github.com/kschrade/blog-post-support/blob/main/caching-and-federations/memoization.js">here</a>.</p>



<h3 class="wp-block-heading"><a href="#distributed-caching" aria-hidden="true" class="aal_anchor" id="distributed-caching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Distributed caching</strong></h3>



<p>An in-memory cache works great until you have more than one implementing service in your federated GraphQL architecture.</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh6.googleusercontent.com/0mg7JBM8PoYzQbSiV-oUkAtvD0m3ybPGvayUepG5zFKSPOlbb5g6UbghtvYXP31E7AFicOzIzp1LQGaU_lXm8NIEy0P-2ILhiectLkIeM8gqPFrEl3IlmMaJUMDG5Zhh2XqIgrgn" alt=""/></figure>



<p>The in-memory cache loses a lot of its efficiency when this happens, mainly due to the fact that none of the local caches are shared.&nbsp;</p>



<p>But don&#8217;t worry; there is a solution to this! A <strong>distributed cache</strong> helps solve this problem!&nbsp;</p>



<h3 class="wp-block-heading"><a href="#using-a-distributed-cache" aria-hidden="true" class="aal_anchor" id="using-a-distributed-cache"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Using a distributed cache</strong></h3>



<p>Distributed caches are things like <a href="https://redis.io/">Redis</a>. With distributed caching, your cache can be spanned across multiple implementing servers or services. You can also use NoSQL databases such as DynamoDB and MongoDB as distributed caches. The main idea is that there is a <strong>shared </strong>object used to save cached values between multiple servers.&nbsp;</p>



<p>If we substitute our existing memoization functions with a cache object that points to a distributed cache instead of a local cache implementation, we get something like this instead:<br></p>



<h2 class="wp-block-heading"><a href="#" aria-hidden="true" class="aal_anchor" id=""><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><img loading="lazy" decoding="async" src="https://lh4.googleusercontent.com/fqKWHO8eQa8QK3g6YHzAkCbXc9av-l7u2rTPKk_Dsx60IOTjCnwEPn82eWGw7QENkLlS6eXNWDtIt9N8egdCUZOtLc_dLIIiigwcSHmu12hD1OVKO7haBPVyBBTKy-mSS559-u5Y" width="624" height="511"></h2>



<p>If you’re using TypeScript, you can strictly type the contract of the cache object that gets passed to your memoization function. You could then switch from using your local in-memory cache to a Redis implementation, a MongoDB one, an Amazon DynamoDB one, etc &#8211; whatever you like!</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">/**
* Generic cache interface that all cache implementations need
* to abide by.
*/

interface ICache {
 get (cacheKey: string): Promise&lt;any&gt;;
 set (cacheKey: string, value: any): Promise&lt;void&gt;;
}

/**
* Your local in-memory cache
*/

class LocalInMemoryCache implements ICache {

 async get (cacheKey: string): Promise&lt;any&gt; {
   // implement local in-memory cache function
 }
 async set (cacheKey: string, value: Promise&lt;any&gt;): Promise&lt;void&gt; {
   // implement local in-memory set function
 }
}

/**
* Your Redis cache
*/

class RedisCache implements ICache {
 private redisConnection: Redis;

 constructor (redisConnection: Redis) {
   this.redisConnection = redisConnection
 }

 async get (cacheKey: string): Promise&lt;any&gt; {
   // implement redis get function
 }
 async set (cacheKey: string, value: Promise&lt;any&gt;): Promise&lt;void&gt; {
   // implement redis set function
 }
}</code></pre>



<h3 class="wp-block-heading"><a href="#caching-the-cache" aria-hidden="true" class="aal_anchor" id="caching-the-cache"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Caching the cache</strong></h3>



<p>If you take another look at the architecture diagram, you’ll notice we point a local cache to a distributed cache. We can actually improve performance even further by using two cache objects: one for the in-memory cache, and the other for the distributed cache.&nbsp;</p>



<p>The idea is that by caching locally first, we remove the need to consult the distributed cache on every request &#8211; we can start by asking the local one first.&nbsp;</p>



<h3 class="wp-block-heading"><a href="#awe-inspiring-benefits-to-distributed-caching" aria-hidden="true" class="aal_anchor" id="awe-inspiring-benefits-to-distributed-caching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Awe-inspiring benefits to distributed caching</h3>



<p>One of the best parts of this approach is how it enables the implementing services in your federated GraphQL architecture to cache things for each other. Let’s expand our architecture a little bit further to include more federated services:</p>



<p><img loading="lazy" decoding="async" width="624" height="511" src="https://lh3.googleusercontent.com/H0AcitS4FawDMOcbuUBzxT06ODTDdyYDMUjkEklHvXe9gFJRPvC0Qy4aELz-ZDkTXL20u72kWWOi9-2ZtPf0dSU-x0Nje5su15MQjos-P_nEc_AyFrnsVyyMHX_YBP3A___nTqSr"></p>



<p>If both implementing services are making calls to the same endpoint in the underlying backend service, they can share that cache value. This is HUGE!&nbsp;</p>



<p>For a practical example, say you have two implementing services: <code>media</code> and <code>product</code>. Suppose a user searches for a product on your site. That search query ends up calling your <code>media</code> implementing service to get the URLs of that product&#8217;s pictures.&nbsp;</p>



<p>Using the approach we’ve described, the URLs would get cached in the distributed cache.&nbsp;</p>



<p>When the user then clicks on the product and issues a product query, the request would go to the implementing service for <code>product</code>but thanks to the distributed cache, the URLs for the product&#8217;s pictures, which would normally need to have been fetched from the media service, can be pulled directly from the cache!&nbsp;</p>



<h3 class="wp-block-heading"><a href="#further-improvement-batching-requests" aria-hidden="true" class="aal_anchor" id="further-improvement-batching-requests"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Further improvement: batching requests</strong></h3>



<p>Now that we have some fantastic caching, we can make our system more efficient by introducing <a href="https://github.com/graphql/dataloader">dataloader</a>. Dataloader is a marvelous package used to batch requests together (check out the <a href="https://github.com/graphql/dataloader">docs</a> to learn more about how it works). We can weave this in right above our API layer but after our caching.&nbsp;</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh6.googleusercontent.com/jGowJT8KxHB_ackvkapyAhFErHfXffxy2gxeQ3RgiIUoVqGp3TqLpmVBYKfvGsR9bUc7jfwMrtpWP1uVxw5cGCBfl32KDz6BfUWx4Z6QE6X0equGvsONhSuUFOnWM7Epa-vfcViQ" alt=""/></figure>



<p>Going back to the product and media example, assume we requested seven products and their images.&nbsp;</p>



<p>If we have three cache <strong>hits</strong> and four <strong>misses</strong>, usually, this would mean we make four calls to both the media and products service for the items that we weren’t able to grab from the cache.</p>



<p>Luckily, dataloader comes to the rescue here!&nbsp;</p>



<p>With dataloader right before the API calls, it bundles up all those requests to both the product and media services to fetch the data.</p>



<p>This is a massive deal. Dataloader makes our caching and API fetching logic way less complicated. Due to dataloader caching everything individually, this approach works for any sized group of items.&nbsp;</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Conclusion</strong></h2>



<p>Well, we made it to the end of our caching journey. We explored caching strategies in a federated GraphQL implementation, starting with zero caching, to two layers of caching and batching with dataloader. We explored the utility of memoization, especially for just getting started caching, and we learned about how it can be composed to improve the way we perform distributed caching as well.&nbsp;</p>



<p>While may be the end of this post, there are millions of other ways to do caching. Two other forms of caching not mentioned in this post are <a href="https://apollo-devhub.netlify.app/collection/state-management">client-side caching</a> and HTTP caching. With client-side caching, you can reduce the amount of data requested via the client, and with HTTP caching using a tool like <a href="https://www.varnish-software.com/community/varnish-cache/">Varnish</a>, your distributed cache becomes a bubble around a service.</p>



<p>These approaches are amazing, and well worth exploring as you venture other ways to further optimize your GraphQL architecture.</p>


Caching Strategies in a Federated GraphQL Architecture


<p>At StockX, we&#8217;ve been running a federated GraphQL implementation for over a year now. Like any distributed system, the rewards it comes with also comes with challenges to overcome. Overall, we&#8217;ve had a positive experience serving our APIs with GraphQL and Apollo Federation.</p>



<p>In this post, I&#8217;d like to highlight some of the most important lessons we’ve learned over the past year running a federated graph in production.</p>



<h2 class="wp-block-heading" id="build-your-schema-as-you-go-dont-try-to-do-it-all-at-once"><a href="#1-build-your-schema-as-you-go-dont-try-to-do-it-all-at-once" aria-hidden="true" class="aal_anchor" id="1-build-your-schema-as-you-go-dont-try-to-do-it-all-at-once"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>1. Build your schema as you go, don&#8217;t try to do it all at once.</h2>



<p>When we first started using GraphQL, we initially tried to create as much of the schema as possible. That worked great for a proof of concept, but it wasn&#8217;t until we got the green light to build it for production that we realized that <strong>upfront schema design</strong> isn&#8217;t the best idea.&nbsp;</p>



<p>Our initial approach was to mirror the shape of the existing RESTful API calls, but this resulted in many extra fields that no one was using. A year later, we are <em>still</em> in the process of removing those unused fields.&nbsp;<br></p>



<p>We now believe in something we call <em>Just In Time Schema (JITS) </em>development. It&#8217;s essentially the term <a href="https://martinfowler.com/bliki/Yagni.html">YAGNI</a> (you ain&#8217;t gonna need it) but applied to schema design; this means that it&#8217;s not until a consumer <em>truly</em> needs a particular field or a type that we expose it.</p>



<h2 class="wp-block-heading"><a href="#2-documenting-the-schema-helps-a-lot" aria-hidden="true" class="aal_anchor" id="2-documenting-the-schema-helps-a-lot"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>2. Documenting the Schema helps. A lot.</h2>



<p>One thing that has been a massive help for consumers of our graph is the ability to document the schema and make that documentation easily consumable. Internally, we had an enormous lack of documentation, and our APIs&#8217; usage relied a little too much upon tribal knowledge.&nbsp;<br></p>



<p>With <a href="https://www.apollographql.com/docs/apollo-server/schema/schema/#documentation-strings">documentation strings</a>, the schema has become a large part of our documentation for consumers. People no longer have to guess what you can do with our API. It&#8217;s been a breath of fresh air, and we no longer have to have to track down which query params work and which ones don&#8217;t.</p>



<h2 class="wp-block-heading"><a href="#3-the-performance-improvement-is-real" aria-hidden="true" class="aal_anchor" id="3-the-performance-improvement-is-real"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>3. The performance improvement is real</h2>



<div class="wp-block-image"><figure class="aligncenter size-large"><img decoding="async" src="https://media.giphy.com/media/dyRT9h6bzA4fDZvPgy/giphy.gif" alt=""/></figure></div>



<p>At StockX, GraphQL brought massive performance increases. We&#8217;re talking SECONDS of improvement &#8211; yes, you read that right. Seconds!&nbsp;</p>



<p>The most critical performance improvement we enjoyed was the reduction of payload size; with GraphQL, payload sizes were up to 7 times smaller! We noticed that every metric we were tracking on mobile devices seemed to improve once we made the payload reduction.</p>



<p>Architecturally, GraphQL does become the choke point for requests. This led us to look into improving multiple parts of our edge layer. Before GraphQL, we used various caching strategies since our serverless handlers and servers did their own caching. The shift to GraphQL allowed us to unify our caching approach and increase the overall strategy.&nbsp;</p>



<p>With a more unified and easier-to-reason-about caching strategy, we were able to reduce the amount of requests to our backend services.&nbsp;</p>



<p><br><em>Stay tuned for my other post titled &#8220;<strong>Caching Approaches in GraphQL Federation</strong>&#8221; to learn how to cache in a federated GraphQL architecture using memoization, data loader, and distributed caching techniques.</em></p>



<h2 class="wp-block-heading"><a href="#4-theres-a-learning-curve" aria-hidden="true" class="aal_anchor" id="4-theres-a-learning-curve"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>4. There&#8217;s a learning curve.</h2>



<p>Most people know how RESTful APIs work &#8211; it&#8217;s become something of a web standard. To me, the learning curve for GraphQL resembles a hockey stick. Unless you&#8217;ve integrated with GraphQL or used GraphQL before, there will undoubtedly be a learning curve because it&#8217;s a much different API style from REST. Since you&#8217;re no longer calling an API to get everything the server will give you back as a response, clients need to know what they want and request it.&nbsp;</p>



<p>Once you wrap your head around GraphQL, you&#8217;ll notice a mindset change from the RESTful world; and it&#8217;s a world where you can move much faster.</p>



<h2 class="wp-block-heading"><a href="#5-faster-development-cycles" aria-hidden="true" class="aal_anchor" id="5-faster-development-cycles"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>5. Faster development cycles.</h2>



<p>After switching over to GraphQL, we&#8217;ve noticed that our tickets complete faster. Instead of &#8220;Team A&#8221; waiting for &#8220;Team B&#8221; to do something, then &#8220;Team C&#8221; to expose the data for &#8220;Team A&#8221;, teams can now more independently due to their ability to traverse through the graph to get the data they need.</p>



<p>For example, when &#8220;Team A&#8221; needs to use a part of the federated graph that they don&#8217;t necessarily own, they don&#8217;t have to wait for other teams to help them. This graphical nature of GraphQL solves more problems than we initially thought.</p>



<h2 class="wp-block-heading"><a href="#6-dont-reinvent-the-wheel" aria-hidden="true" class="aal_anchor" id="6-dont-reinvent-the-wheel"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>6. Don&#8217;t reinvent the wheel.</h2>



<p>GraphQL is excellent, but it still faces the same problems as any other technology out in the wild. For example, scaling is a challenge you&#8217;ll want to tackle with well-known architectural best practices.&nbsp;</p>



<p>That means using Apollo Federation to implement a microservice-like architecture by decoupling our graph by <em>concern</em>; this enables teams to manage their distinct parts of a single federated GraphQL API, scale traffic more effectively, and ship code faster.</p>



<p>We initially tried to build our own &#8220;pure&#8221; GraphQL server/schema. It wasn&#8217;t until we exposed it to production traffic and experienced common challenges serving a monolithic API that we realized we needed to follow trusty distributed computing best practices.</p>



<h2 class="wp-block-heading"><a href="#7-graphql-federation-scales-well-horizontally" aria-hidden="true" class="aal_anchor" id="7-graphql-federation-scales-well-horizontally"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>7. GraphQL federation scales well horizontally.</h2>



<p>After putting our federated GraphQL implementation into production, we found that horizontal scaling was the best way for us to serve large traffic loads.&nbsp;</p>



<p>We use NodeJS- and with NodeJS being single-threaded, it allows for more requests to be handled simultaneously.&nbsp;</p>



<p>We still have to preemptively scale our systems before large traffic spikes like a push notification or other marketing events. But one of the beautiful parts of using Federation is that we can scale <em>only</em> the implementing services affected by the event.&nbsp;</p>



<p>For example, if we send out an email to clients about a fantastic blog post, we can scale the blog portion of our federated architecture and leave everything else the same. This is great when we look at the cost of running our services. Due to not having to scale everything, we save money.</p>



<h2 class="wp-block-heading"><a href="#8-read-then-keep-reading" aria-hidden="true" class="aal_anchor" id="8-read-then-keep-reading"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>8. Read. Then, keep reading.</h2>



<div class="wp-block-image"><figure class="aligncenter size-large"><img decoding="async" src="https://media.giphy.com/media/NFA61GS9qKZ68/giphy.gif" alt=""/></figure></div>



<p>We have had some stumbles while adopting GraphQL. The team at StockX has had no prior experience with GraphQL.&nbsp;</p>



<p>So we read, and then read, then read even more. The amount of knowledge out there has helped us make more informed decisions. Some of the articles we found helpful were:</p>



<ul class="wp-block-list"><li><a href="https://graphql.org/learn/best-practices/">GraphQL Best Practices from GraphQL.org</a></li><li><a href="https://relay.dev/graphql/connections.htm">GraphQL Cursor Specification from Relay.dev</a></li><li><a href="https://graphql.org/learn/pagination/">How to Handle Pagination from GraphQL.org</a></li></ul>



<h2 class="wp-block-heading"><a href="#9-graphql-forces-domain-conversations" aria-hidden="true" class="aal_anchor" id="9-graphql-forces-domain-conversations"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>9. GraphQL forces domain conversations.</h2>



<p>When we first started GraphQL, our types were a mess. Sure, our endpoints <em>structurally </em>returned the same payload as the RESTful API we had in place before, and that made the front-ends work, but it was a mess to work with.&nbsp;</p>



<p>Eventually, we had the opportunity to design the graph from scratch again, starting clean.&nbsp;</p>



<p>We used this opportunity to start conversations which led to a better understanding of the division of responsibilities and relationships between services and types. We discussed what fields belong in which type, what to do with our massive existing types, and how to break them into smaller, better namespaced types. We’re now at a point where our dedicated selection of types work much better for us.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>It was a lot of work to migrate to GraphQL, but looking back at all that work over the last year, I <em>still </em>think that migration was a major success and was incredibly impactful to the way we work today. GraphQL has enabled us to have faster development cycles, push smaller chunks to production with fewer problems, rethink our UX, among so many other improvements.</p>


Backend