Enhance customer experiences with Apollo GraphOS


<p class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="" data-line="">HTTPRoute</code> rule that looks like this:</p>



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



<p class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">First off, the developers can delete their entire <code class="" data-line="">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 class="" data-line="">subscription</code> field:</p>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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" data-line="">@app.get(&quot;/items/{item_id}&quot;)
async def read_item(item_id: int) -&gt; Item:
  return Item.load(item_id)</code></pre>



<p class="wp-block-paragraph">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" data-line="">rules:
 - matches:
     - path:
         type: RegularExpression
         value: /items/\d+/</code></pre>



<p class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="" data-line="">NetworkPolicy</code> that looks something like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml" data-line="">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 class="wp-block-paragraph">Here we’re denying all ingress traffic for all pods unless it comes from the API Gateway.</p>



<p class="wp-block-paragraph">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 class="wp-block-paragraph">With Apollo Federation, services can set up their dependencies declaratively and let the router take care of the rest. In this example, the <code class="" data-line="">totalCost</code> field requires a <em>different</em> service’s <code class="" data-line="">products</code> field (specifically, the <code class="" data-line="">price</code> and <code class="" data-line="">shipping</code> subfields).</p>



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



<p class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="" data-line="">#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


<p class="wp-block-paragraph">How many routes do you have in your MERN stack? As your API grows with more routes, you may start creating multiple MERN stacks in a backend-for-frontend (BFF) architecture to help manage those routes. In creating additional MERN stacks, are you duplicating code in those BFFs? Using Federated GraphQL to have a single data access layer for your company can help you manage your MERN stack apps and provide an improved developer experience for everyone.</p>



<p class="wp-block-paragraph">In recent years, GraphQL has gained significant traction in the tech industry thanks to its efficiency and flexibility. GraphQL provides a simple and more dynamic approach to data fetching than traditional RESTful APIs. If you&#8217;ve been building applications using MongoDB, Express, React, and Node.js (<a href="https://www.mongodb.com/mern-stack">the MERN stack</a>), it&#8217;s high time you considered using Apollo Server to make your stack speak GraphQL.</p>



<p class="wp-block-paragraph">In this post, we will explore how you can modernize your MERN stack application to use GraphQL with Apollo Server. But before we jump into how to do that, why should you?</p>



<h2 class="wp-block-heading"><a href="#why-should-you-add-graphql-to-your-mern-stack" aria-hidden="true" class="aal_anchor" id="why-should-you-add-graphql-to-your-mern-stack"><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>Why should you add GraphQL to your MERN Stack?</strong></h2>



<p class="wp-block-paragraph">GraphQL provides many benefits (read more about <a href="https://www.apollographql.com/docs/intro/benefits/">why you should adopt GraphQL</a>) but there are some specific ones for a MERN stack! GraphQL is declarative and provides an easy to understand the connection between your defined schema and your MongoDB queries in code.&nbsp; In your current server, you probably have multiple routes using <code class="" data-line="">express.Router</code> that serve the API endpoints for your client app:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">import express from &quot;express&quot;;
import db from &quot;../db/conn.mjs&quot;;
import { ObjectId } from &quot;mongodb&quot;;

const router = express.Router();

// This section will help you get a list of all the records.
router.get(&quot;/&quot;, async (req, res) =&gt; {
  let collection = await db.collection(&quot;records&quot;);
  let results = await collection.find({}).toArray();
  res.send(results).status(200);
});

// This section will help you get a single record by id
router.get(&quot;/:id&quot;, async (req, res) =&gt; {
  let collection = await db.collection(&quot;records&quot;);
  let query = {_id: new ObjectId(req.params.id)};
  let result = await collection.findOne(query);

  if (!result) res.send(&quot;Not found&quot;).status(404);
  else res.send(result).status(200);
});</code></pre>



<p class="wp-block-paragraph">This code can become hard to manage as your API grows and this could lead to duplicating code (like your db queries) between routes. It will also be difficult for any new developers coming on to the project. Imagine you have an app-server with hundreds of routes, a new developer onboarding to your team will need to understand how these routes are organized, how they serve different frontend components, and how these map to different database queries. The permutations between these three different pieces of logic could be dizzying to even a seasoned developer.</p>



<p class="wp-block-paragraph">With GraphQL, you have the flexibility to define the schema and write resolvers that connect to your DB queries:</p>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">//schema.graphql
type Query {
  record(id: ID!): Record
}
type Record {
  id: ID
  name: String
  position: String
  level: String
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">//resolvers.mjs
const resolvers = {
  Query: {
    async record(_, { id }, context) {
      let collection = await db.collection(&quot;records&quot;);
      let query = { _id: new ObjectId(id) };

      return await collection.findOne(query);
    },
    async records(_, __, context) {
      let collection = await db.collection(&quot;records&quot;);
      return await collection.find({}).toArray();
    },
  },
};</code></pre>



<p class="wp-block-paragraph">Anyone who has worked on a GraphQL project can quickly make the connection and navigate your code structure. You no longer have to manage bespoke endpoints.</p>



<p class="wp-block-paragraph">If you are using TypeScript in a MERN stack app or microservice, you have the client and server code in the same workspace enabling you to use <a href="https://the-guild.dev/graphql/codegen/docs/getting-started">code generation</a> on your GraphQL schema. This can generate types that can be used on your server’s resolvers and types for your client’s operations, both work seamlessly with <a href="https://www.apollographql.com/docs/apollo-server/workflow/generate-types#setting-up-your-project"><code class="" data-line="">@apollo/server</code></a> and <a href="https://www.apollographql.com/docs/react/development-testing/static-typing#setting-up-your-project"><code class="" data-line="">@apollo/client</code></a>. In my opinion, this produces part of the ideal developer experience 😍</p>



<p class="wp-block-paragraph">With GraphQL, you can have your client application make only one request which creates only one invocation of your API. This eliminates the need to manage custom API endpoints and gives a simple to understand pricing on your invocations (i.e. the page was viewed 1M times, so you have 1M invocations of your Function).</p>



<p class="wp-block-paragraph">So if you are building a MERN stack app or microservice, you should upgrade it to speak GraphQL. Let’s learn how you can quickly do that!</p>



<h2 class="wp-block-heading"><a href="#upgrading-your-server-to-speak-graphql" aria-hidden="true" class="aal_anchor" id="upgrading-your-server-to-speak-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><strong>Upgrading your server to speak GraphQL</strong></h2>



<p class="wp-block-paragraph">The first step to upgrade your server is to install the necessary GraphQL packages:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session" data-line="">npm install @apollo/server @apollo/subgraph graphql graphql-tag</code></pre>



<p class="wp-block-paragraph"><em>Note: We&#8217;re setting up this GraphQL API using <a href="https://www.apollographql.com/docs/federation">Apollo Federation</a>. It&#8217;s important that you secure your subgraph to be used with the <a href="https://www.apollographql.com/docs/router">Apollo Router</a>. For more information on securing your&nbsp;subgraphs with a&nbsp;router, see&nbsp;<a href="https://www.apollographql.com/docs/graphos/graphs/securing-a-subgraph">this article</a>.</em></p>



<p class="wp-block-paragraph">Next, you’ll need to define a GraphQL schema based on the functionality you want to expose in your MERN stack. In this blog post, we’ll be using the <a href="https://www.mongodb.com/languages/mern-stack-tutorial">MERN stack tutorial</a> as our example.e have a docs tutorial specifically for <code class="" data-line="">@apollo/server</code> **LINK ONCE LIVE** if you want to jump straight to that.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">To follow along, register for <a href="https://www.mongodb.com/try?utm_campaign=devrel&amp;utm_source=cross-post&amp;utm_medium=cta&amp;utm_content=apollo-mern&amp;utm_term=stanimira.vlaeva">MongoDB Atlas</a> and deploy a forever-free database cluster. Atlas is MongoDB’s multi-cloud database integrated with a suite of data services. After deploying your free cluster, proceed by cloning the <a href="https://github.com/mongodb-developer/mern-stack-example">MERN stack project</a>. Follow the instructions outlined in the repository to set up and run the Node.js and React applications.</p>
</blockquote>



<p class="wp-block-paragraph">Continuing from the MERN stack tutorial, we’ll start by defining a schema similar to the routes currently defined. We’re only going to focus on the Query/READ of the schema in this post:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">//schema.graphql
type Query {
  record(id: ID!): Record
  records: [Record]
}

type Record {
  id: ID
  name: String
  position: String
  level: String
}</code></pre>



<p class="wp-block-paragraph">The resolvers code is going to look similar to some of the code you have already written wherever you define your routes. From the schema defined above, we can pull the routes code into the resolvers:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">//resolvers.mjs
const resolvers = {
  Record: {
    id: (parent) =&gt; parent.id ?? parent._id,
  },
  Query: {
    async record(_, { id }, context) {
      let collection = await db.collection(&quot;records&quot;);
      let query = { _id: new ObjectId(id) };

      return await collection.findOne(query);
    },
    async records(_, __, context) {
      let collection = await db.collection(&quot;records&quot;);
      const records = await collection.find({}).toArray();
      return records;
    },
  },
};

export default resolvers;</code></pre>



<p class="wp-block-paragraph">Lastly, we need to expose the <code class="" data-line="">/graphql</code> route in our express app. In your server.js (or wherever you define your express app), we’ll use <code class="" data-line="">@apollo/server</code> to expose the <code class="" data-line="">/graphql</code> route:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">import express, { json } from &quot;express&quot;;
import &quot;./loadEnvironment.mjs&quot;;
import cors from &quot;cors&quot;;
import gql from &quot;graphql-tag&quot;;
import { ApolloServer } from &quot;@apollo/server&quot;;
import { buildSubgraphSchema } from &quot;@apollo/subgraph&quot;;
import { expressMiddleware } from &quot;@apollo/server/express4&quot;;
import resolvers from &quot;./resolvers.mjs&quot;;
import { readFileSync } from &quot;fs&quot;;

const PORT = 5050;
const app = express();

app.use(cors());
app.use(express.json());

const typeDefs = gql(
  readFileSync(&quot;schema.graphql&quot;, {
    encoding: &quot;utf-8&quot;,
  })
);

const server = new ApolloServer({
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
});
await server.start();

app.use(&quot;/graphql&quot;, cors(), json(), expressMiddleware(server));

app.listen(PORT, () =&gt; {
  console.log(`Server listening on port ${PORT}`);
});</code></pre>



<p class="wp-block-paragraph">Now you should be able to run your server project and visit <code class="" data-line="">/graphql</code> to see Apollo Explorer 🎉. Next we need to upgrade the client project to use GraphQL.</p>



<h2 class="wp-block-heading"><a href="#upgrading-your-client-to-use-graphql" aria-hidden="true" class="aal_anchor" id="upgrading-your-client-to-use-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><strong>Upgrading your client to use GraphQL</strong></h2>



<p class="wp-block-paragraph">The first step to upgrade your client is to install the necessary GraphQL packages:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session" data-line="">npm install @apollo/client graphql</code></pre>



<p class="wp-block-paragraph">Next, we need to add the <code class="" data-line="">ApolloProvider</code> to our React app:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">// src/index.js
import {
  ApolloClient,
  InMemoryCache,
  ApolloProvider
} from &quot;@apollo/client&quot;;

const client = new ApolloClient({
  uri: &quot;http://localhost:5050/graphql&quot;,
  cache: new InMemoryCache(),
  connectToDevTools: process.env.NODE_ENV == &quot;production&quot; ? true : false
});

const container = document.getElementById(&quot;root&quot;);
const root = createRoot(container);
root.render(
  &lt;React.StrictMode&gt;
    &lt;BrowserRouter&gt;
      &lt;ApolloProvider client={client}&gt;
        &lt;App /&gt;
      &lt;/ApolloProvider&gt;
    &lt;/BrowserRouter&gt;
  &lt;/React.StrictMode&gt;
);</code></pre>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph"><code class="" data-line="">connectToDevTools</code> is what enables us to have the Apollo Client Devtools appear as an “Apollo” tab in your web browser inspector. You wouldn’t want to run this in production.</p>
</blockquote>



<p class="wp-block-paragraph">Now we’re ready to start utilizing the hooks <code class="" data-line="">@apollo/client</code> provides to execute GraphQL operations. You’ll need to pick a UI to start with that is associated with the schema you designed. Since we are doing the query portion of the records, we can hook up the <code class="" data-line="">recordList.js</code> to our GraphQL route:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">// recordList.js
import React from &quot;react&quot;;
import { Link } from &quot;react-router-dom&quot;;
import { gql, useQuery } from &quot;@apollo/client&quot;;

export const GET_RECORDS = gql`
  query GetRecords {
    records {
      id
      name
      position
      level
    }
  }
`;
const Record = ({ record }) =&gt; {
  return (
    &lt;tr&gt;
      &lt;td&gt;{record.name}&lt;/td&gt;
      &lt;td&gt;{record.position}&lt;/td&gt;
      &lt;td&gt;{record.level}&lt;/td&gt;
    &lt;/tr&gt;
  );
};
export default function RecordList() {
  const { loading, error, data } = useQuery(GET_RECORDS);

  if (loading) return &lt;p&gt;Loading...&lt;/p&gt;;
  if (error) return &lt;p&gt;Error : {error.message}&lt;/p&gt;;

  // This following section will display the table with the records of individuals.
  return (
    &lt;div&gt;
      &lt;h3&gt;Record List&lt;/h3&gt;
      &lt;table className=&quot;table table-striped&quot; style={{ marginTop: 20 }}&gt;
        &lt;thead&gt;
          &lt;tr&gt;
            &lt;th&gt;Name&lt;/th&gt;
            &lt;th&gt;Position&lt;/th&gt;
            &lt;th&gt;Level&lt;/th&gt;
            &lt;th&gt;Action&lt;/th&gt;
          &lt;/tr&gt;
        &lt;/thead&gt;
        &lt;tbody&gt;
          {data?.records.map((record) =&gt; (
            &lt;Record record={record} key={record.id} /&gt;
          ))}
        &lt;/tbody&gt;
      &lt;/table&gt;
    &lt;/div&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">Now you should be able to start your client application and the records will be loaded through your GraphQL route ✨</p>



<p class="wp-block-paragraph">The next step is to start planning the next UI you want to build or migrate to your new GraphQL route with this iterative process:</p>



<ol class="wp-block-list">
<li>Define the operation and schema &#8211; start with the ideal GraphQL operation for the UI you’re trying to build and write the schema to enable that operation.</li>



<li>In your server project, update the schema and write the necessary resolvers</li>



<li>In your client project, add the operation and add to your UI component</li>
</ol>



<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 class="wp-block-paragraph">In this blog post, we discussed some of the benefits of using GraphQL in a MERN stack application or microservice and how it simplifies the routes defined on the server side. Anyone who has used GraphQL in the past will be able to get up to speed quickly in your project and an upgraded developer experience. We also walked through how you can upgrade your project to speak GraphQL with <code class="" data-line="">@apollo/server</code> and <code class="" data-line="">@apollo/client</code> in just a couple of steps using the <a href="https://www.mongodb.com/languages/mern-stack-tutorial">MERN stack tutorial</a> as our example. You can check out our docs that go into more depth on setting up the server portion of the project. Additionally, if you’d like to explore MongoDB in a cloud environment, you can register and deploy a free cluster in <a href="https://www.mongodb.com/try?utm_campaign=devrel&amp;utm_source=cross-post&amp;utm_medium=cta&amp;utm_content=apollo-mern&amp;utm_term=stanimira.vlaeva">MongoDB Atlas</a>.</p>



<p class="wp-block-paragraph">Now that you’ve started your journey into GraphQL, you can start building and iterating on your app faster. You can integrate GraphOS for <a href="https://www.apollographql.com/docs/graphos/delivery/schema-checks">schema checks</a> or <a href="https://www.apollographql.com/docs/graphos/routing/cloud">routing requests across multiple GraphQL services</a>, like a 3rd party GraphQL API you’re integrating with.&nbsp;</p>



<p class="wp-block-paragraph">You probably will also have questions/choices come up as you build and we’re here to help! Come join us in the <a href="https://discord.gg/cnfjXU92hZ">Apollo Discord Server</a> and ask your questions. You can ping me directly (@watson) or any of the Developer Advocates in there. We plan regular streams that turn into videos on our YouTube and it’s the best place to catch that content first. Hope to see you there!</p>


Modernize your MERN Stack with GraphQL and GraphOS


<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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 1. Your Monolith</figcaption></figure>



<p class="wp-block-paragraph">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="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 2. Bound to the Monolith</figcaption></figure>



<p class="wp-block-paragraph">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 class="wp-block-paragraph">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="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 3. First successful subgraph migration</figcaption></figure>



<p class="wp-block-paragraph">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 class="wp-block-paragraph">Do note, that some client work <em>may</em> be required here to bind newly created or improved client operations/queries.&nbsp;</p>



<p class="wp-block-paragraph">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 class="wp-block-paragraph">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="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 4. Learning from the first and implementing second subgraph</figcaption></figure>



<p class="wp-block-paragraph">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="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 5. Strangler Fig fully applied to Monolith</figcaption></figure>



<p class="wp-block-paragraph">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="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">figure 6. Strangler Fig worked. New modern services implemented.</figcaption></figure>



<p class="wp-block-paragraph">Figure 2 above demonstrates two domains which were previously served by the monolith, now being served by the new modern microservices. </p>



<p class="wp-block-paragraph">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="auto, (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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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 class="wp-block-paragraph">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

Designing our GraphQL Schema for Propel, an analytics platform

Designing the GraphQL schema for Propel, an analytics API platform


<p class="wp-block-paragraph">Let’s consider the core promise of GraphQL:</p>



<p class="wp-block-paragraph"><strong>Get exactly what you need and nothing more with a single query.</strong></p>



<p class="wp-block-paragraph">Does it sound amazing? Absolutely. But if you’ve ever tried to implement GraphQL for an entire engineering team, you’ve probably realized that it’s not quite as simple as it sounds to achieve. For any dev in the organization to be able to get everything they need in a single query, <em>everything</em> that anyone could need has to exist in a single graph.&nbsp;</p>



<p class="wp-block-paragraph">The concept of a single graph for everything seems all but impossible when you think about it from a compliance perspective, and that was one of the biggest challenges we faced when we started to scale up our use of GraphQL at Priceline. As a travel booking platform that supports millions of customers around the world, our backend services contain quite a bit of PCI data that can’t be made accessible to our client apps.&nbsp;</p>



<p class="wp-block-paragraph">One graph → one endpoint → client apps have access to everything, including cardholder information and other sensitive data. Right?</p>



<p class="wp-block-paragraph">Well it turns out, not necessarily. With a <a href="https://www.apollographql.com/blog/announcement/backend/the-supergraph-a-new-way-to-think-about-graphql/">supergraph</a>, we can have a single graph that unifies all of all of our data and services, including sensitive data, but we can selectively choose which parts of the graph are exposed to various audiences, like app devs. In this post I’ll walk you through how we did this for the Priceline supergraph and how you can set it up yourself using contracts in Apollo Studio.</p>



<h2 class="wp-block-heading"><a href="#is-a-supergraph-worth-it" aria-hidden="true" class="aal_anchor" id="is-a-supergraph-worth-it"><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>Is a supergraph worth it?</h2>



<p class="wp-block-paragraph">Let’s take a step back – is it even worth it to put everything into one graph? Couldn’t we just have entirely separate graphs for internal systems that require sensitive data and for client apps that don’t? We could, and at Priceline we actually did at first, but we would end up with a lot of duplicative maintenance work that could be avoided.</p>



<p class="wp-block-paragraph">There’s always going to be overlap between what internal systems need and what client apps need. For example, our booking graph, which was not part of the supergraph, contained airline policy schema used for display when a customer was booking a flight. Our native apps teams wanted to display this information to a customer viewing flight information, earlier in the funnel. However, they did not want the overhead of multiple network requests. Normally this would result in duplicating the airline policy schema inside the supergraph. Not ideal.</p>



<p class="wp-block-paragraph">And that’s just one example. To provide a specific subset of services for a certain audience or experience that differed from an already existing graph, we either had to use preexisting REST APIs or create an entirely new graph to support it. IT systems app? Separate graph. Partner API? Separate graph.&nbsp;</p>



<p class="wp-block-paragraph">With a supergraph, we could create a single source of truth for definitions of every entity in our data model (hotel, flight, rental car, customer, etc), eliminating a huge amount of maintenance work associated with these disparate graphs. For us, it was worth it.</p>



<h2 class="wp-block-heading"><a href="#restricting-access-to-sensitive-data-in-a-supergraph" aria-hidden="true" class="aal_anchor" id="restricting-access-to-sensitive-data-in-a-supergraph"><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>Restricting access to sensitive data in a supergraph</h2>



<p class="wp-block-paragraph">As a single source of truth, our supergraph schema contains everything, including sensitive data. So we can’t just have every application query the endpoint for the entire supergraph directly. Instead, we need to define which parts of the supergraph certain applications are allowed to access. We can do this by creating contract graphs in Apollo Studio.</p>



<h3 class="wp-block-heading"><a href="#contract-graphs-filtered-representations-of-the-supergraph" aria-hidden="true" class="aal_anchor" id="contract-graphs-filtered-representations-of-the-supergraph"><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>Contract graphs: filtered representations of the supergraph</h3>



<p class="wp-block-paragraph">Contract graphs are variants of the overall supergraph that only contain a filtered subset of the fields and types defined in the supergraph schema. Deriving a contract graph’s schema from the supergraph schema requires two things:</p>



<ol class="wp-block-list"><li>Using the <code class="" data-line="">@tag</code> directive to apply tags to fields, interfaces, objects, and unions in your subgraph schemas.</li><li>Creating a contract in Apollo Studio that defines which tags should be included or excluded from the contract schema</li></ol>



<p class="wp-block-paragraph">Once you’ve tagged your subgraph schemas and created your contract in Apollo Studio, the contract graph schema will automatically be derived from the supergraph schema whenever it’s composed in Studio. The contract schema can be used to power Apollo Router or Apollo Gateway to create a running contract graph with its own endpoint.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="470" src="https://wp.apollographql.com/wp-content/uploads/2022/09/image1-1024x470.png" alt="" class="wp-image-15806" srcset="https://wp.apollographql.com/wp-content/uploads/2022/09/image1-1024x470.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/09/image1-300x138.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/09/image1-768x353.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/09/image1-1536x705.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/09/image1-1200x551.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/09/image1-1980x909.png 1980w, https://wp.apollographql.com/wp-content/uploads/2022/09/image1.png 1999w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h3 class="wp-block-heading"><a href="#using-contracts-to-filter-out-pci-data" aria-hidden="true" class="aal_anchor" id="using-contracts-to-filter-out-pci-data"><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>Using contracts to filter out PCI data</h3>



<p class="wp-block-paragraph">At Priceline, we use a contract graph to prevent clients from sending and requesting cardholder data through the supergraph, to the booking subgraph. The fewer touchpoints with this sensitive information, the better. As I mentioned earlier, the booking subgraph also contains airline policy information which we do need client apps to have access to so that we can display it to customers on a variety of pages</p>



<p class="wp-block-paragraph">Using the <code class="" data-line="">@tag</code> directive, we tagged all of the sensitive entities in the Checkout subgraph with <code class="" data-line="">PCI</code>. Then, we defined a contract in Apollo Studio that excludes anything tagged with <code class="" data-line="">PCI</code>. The derived contract graph is what our client apps query rather than the supergraph itself.</p>



<p class="wp-block-paragraph"><strong>That’s it.</strong></p>



<p class="wp-block-paragraph">Applying tags within your subgraph schemas and creating a contract in Studio is all you need to do to create contract graphs that remove access to sensitive data. And, because contract graphs derive their schema from the supergraph, they are automatically kept up-to-date with any changes in the supergraph schema. Modifying the entities included in a contract graph is as easy as editing tags in your subgraph schema or the filters in Apollo Studio.</p>



<h2 class="wp-block-heading"><a href="#whats-next-for-graphql-at-priceline" aria-hidden="true" class="aal_anchor" id="whats-next-for-graphql-at-priceline"><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 for GraphQL at Priceline</h2>



<p class="wp-block-paragraph">At Priceline, our supergraph already powers nearly all of our experiences, but we’re still just getting started. In the future, we’re planning on using contract graphs to improve our Travel Agents API, our internal customer support application, and more.</p>


How Priceline.com manages PCI compliance with GraphQL


<p class="wp-block-paragraph">When creating a GraphQL server there are two artifacts required by the GraphQL engine: a schema, which defines all the types and fields, and the resolvers, which are the collection of functions that are called to return the data for those types. Since GraphQL can be implemented in many different programming languages, there are of course many tools and libraries you can use to create a server and execute requests. Whenever there are multiple options there will also be pros and cons for each choice and differing opinions on which are best. </p>



<h2 class="wp-block-heading"><a href="#schema-first" aria-hidden="true" class="aal_anchor" id="schema-first"><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>Schema-First </h2>



<p class="wp-block-paragraph">Schema-first, or SDL-first, is one of the more common approaches to creating a GraphQL server. It requires that you define the schema in the Schema Definition Language (SDL) and also write the resolvers that execute and return data at runtime. This pattern is popular in languages that do not have a type system, like JavaScript, because the GraphQL engine is providing this API type-safety for us. It is also the pattern used by many popular GraphQL servers, like <a href="https://github.com/apollographql/apollo-server">apollo-server</a>, which adds to the exposure of the pattern, as new GraphQL developers will likely see this pattern first when learning GraphQL for the first time.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line=""># schema.graphql using schema-first
type Query {
  hello: String
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">// resolvers.js using schema-first
const resolvers = {
  Query: {
    hello: () =&gt; &#039;hello world&#039;
  }
};</code></pre>



<h2 class="wp-block-heading"><a href="#code-only" aria-hidden="true" class="aal_anchor" id="code-only"><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>Code-Only</h2>



<p class="wp-block-paragraph">Code-only, or code-first, is an approach where you only need to write the resolvers for the GraphQL server and a build tool can compile the schema and SDL based on the types or annotations included in the code. This is more common in type-safe languages, such as <a href="https://github.com/ExpediaGroup/graphql-kotlin">graphql-kotlin</a>, where you can run reflections against source code, however, it can be used by any GraphQL server language.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin" data-line="">// schema.kt using code-only
class Query {
  fun hello(): String = &quot;hello world&quot;
}</code></pre>



<h2 class="wp-block-heading"><a href="#generated-schemas" aria-hidden="true" class="aal_anchor" id="generated-schemas"><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>Generated Schemas</h2>



<p class="wp-block-paragraph">The term <a href="https://www.apollographql.com/blog/tooling/apollo-codegen/generated-graphql-schemas-and-schema-design/" target="_blank" rel="noreferrer noopener">generated schema</a> is separate from schema-first and code-only. This refers to tools that can take some external data types or non-GraphQL schema and generate a GraphQL schema and/or the resolvers with the same types. These tools allow you to take existing data sources, like OpenAPI or SQL databases, and quickly add a GraphQL API on top of them with the same types. The result is an API server that you deploy and manage, but you don’t control the types or data that the API clients can ask for. Instead of comparing all GraphQL API patterns, we will only focus on the first two, which allow you to define types separate from your underlying data sources.</p>



<h2 class="wp-block-heading"><a href="#pattern-misconceptions" aria-hidden="true" class="aal_anchor" id="pattern-misconceptions"><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>Pattern Misconceptions</h2>



<p class="wp-block-paragraph">There are a few misconceptions that we often hear from the GraphQL community that we would like to address.</p>



<h4 class="wp-block-heading"><a href="#rumor-schema-first-leads-to-better-schema-design" aria-hidden="true" class="aal_anchor" id="rumor-schema-first-leads-to-better-schema-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><em>“Rumor</em>: <em>Schema-first leads to better schema design”</em></h4>



<p class="wp-block-paragraph">Schema-first is sometimes framed as a “better” pattern because it requires you to write out the schema types separate from the runtime code. The reasoning is that developers will have to think about the types they are returning because the types are defined in a separate location. Hopefully, this also makes your code more readable as code reviewers can easily go to one location to see only the API changes and not internal implementation details in the resolvers. While you do have to write the schema manually, schema-first does not guarantee your API schema will be better.</p>



<p class="wp-block-paragraph">Often when first learning GraphQL, developers will try to map existing API patterns from REST or only think about the underlying data sources, rather than the users of their API. What defines “good” schema design is going to come from the clients of the API, not the server maintainers. If a client can get the data it needs with minimal effort and without the need to transform the data themselves, it will be an easy API to consume. There are many patterns for <a href="https://www.apollographql.com/blog/backend/federation/federated-schema-design">good schema design</a>; regardless of how you build the schema, try thinking about your end consumers. When building with code-only you still need to have the types defined, and they should be planned and thought of ahead of time the same way you do with schema-first.</p>



<h4 class="wp-block-heading"><a href="#rumor-you-cant-see-the-sdl-with-code-only" aria-hidden="true" class="aal_anchor" id="rumor-you-cant-see-the-sdl-with-code-only"><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><em>“<em>Rumor</em></em>: <em>You can’t see the SDL with code-only”</em></h4>



<p class="wp-block-paragraph">In all of the above patterns, the runtime artifacts of the GraphQL server are still the same. We need a schema, which defines all the types according to the <a href="https://spec.graphql.org/">GraphQL spec</a>, and the resolvers to execute code. If developers have concerns about where the schema types can be found, using tooling like a build plugin, you can generate an SDL file at build time, like how <a href="https://opensource.expediagroup.com/graphql-kotlin/docs/plugins/gradle-plugin-tasks#graphqlgeneratesdl">graphql-kotlin includes a Gradle plugin</a>. Another option is to generate the SDL file from introspection, by using a tool like <a href="https://www.apollographql.com/docs/rover/commands/graphs#graph-introspect">Rover CLI</a>. Once you have the SDL file, you can check in the changes to source control or upload it to a schema registry, like <a href="https://www.apollographql.com/studio">Apollo Studio</a>, to easily share schema changes and explore the types directly, or even make real queries against your data.</p>



<p class="wp-block-paragraph">SDL files abstract our types from our code and allow all developers, both client-side and server-side, to design, discuss, and review API changes in a common language. Even with code-first as your implementation tool, SDL files can be used for everything else developers do that is not writing code, whether that is architecting APIs in design docs or offering review comments in line with code changes. Instead of focusing on tooling, consider adopting a <a href="https://www.apollographql.com/blog/community/graphql-champions/10-best-practices-for-schema-stewardship/">schema stewardship model</a> that encourages collaboration and iteration that will allow your team to maintain your API design principles, regardless of the implementation details of the server.</p>



<h4 class="wp-block-heading"><a href="#rumor-code-only-is-easier-because-there-is-less-code-to-maintain" aria-hidden="true" class="aal_anchor" id="rumor-code-only-is-easier-because-there-is-less-code-to-maintain"><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><em>“<em>Rumor</em></em>: <em>Code-only is easier because there is less code to maintain”</em></h4>



<p class="wp-block-paragraph">In the schema-first approach you can have errors because the names did not match up exactly between the SDL and the resolvers. Most of the time this can be caught with builds or tests, but this still can lead to runtime errors. Code-only solves this problem by having you write the types essentially in line with the resolvers which in theory is less code to maintain.</p>



<p class="wp-block-paragraph">For small examples, this pattern looks easier if you have a good reflection and type system, but not all code-only libraries are built the same. The reference GraphQL implementation, <a href="https://github.com/graphql/graphql-js">graphql-js</a>, is actually code-only, and only through external libraries, initially created by Apollo, did it become easy to create a server through the schema-first approach. The original builder pattern required much more code to include types in a non-typed language.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">// server.js using code-only graphql-js
const schema = new GraphQLSchema({
 query: new GraphQLObjectType({
   name: &#039;Query&#039;,
   fields: {
     hello: {
       type: GraphQLString,
       resolve: () =&gt; ‘hello world’
     }
   }
 })
});</code></pre>



<p class="wp-block-paragraph">If you are choosing schema-first, you also still have the option to generate code in the reverse. Because GraphQL schema is type-safe, you can generate code from GraphQL that can be used in the server and resolvers. Tools like <a href="https://www.graphql-code-generator.com/plugins/typescript/typescript-resolvers">graphql-code-gen</a> allow you to generate the Typescript types so your resolvers have the guaranteed type safety, and <a href="https://gqlgen.com/">gqlgen</a> takes it even further, allowing you to specify directives in the schema which will generate some of the resolver code.</p>



<h4 class="wp-block-heading"><a href="#rumor-schema-first-makes-it-difficult-to-have-a-modular-schema" aria-hidden="true" class="aal_anchor" id="rumor-schema-first-makes-it-difficult-to-have-a-modular-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><em>“<em>Rumor</em></em>: <em>Schema-first makes it difficult to have a modular schema”</em></h4>



<p class="wp-block-paragraph">Some schema-first libraries only support passing in a single schema definition. If you want to split up your GraphQL server into different modules, each of which contains its types and resolvers, this can be more difficult to accomplish with just one library. Code-only, by its nature, solves this issue by having the types inlined so sharing resolvers also share the types and they can be merged back together. While code-only might have been the best way to have a modular schema a few years ago, the GraphQL ecosystem has evolved as more developers use GraphQL and build more tooling, and schema-first libraries have been updated to support multiple type definitions.</p>



<p class="wp-block-paragraph">For those looking to just split up a single server into smaller modules, using the built-in extend keyword from GraphQL spec can usually solve most problems.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">// reviews.js
const reviewsSDL = gql`
  extend type Query {
    allReviews: [Review]
  }

  extend type Product {
    reviews: [Review]
  }

  # ...other types
`;

const reviewsResolvers = {
  Query: {
    allReviews: () =&gt; callReviewsDB()
  },
  Product: {
    reviews: (parent) =&gt; reviewsForProduct(parent.id)
  }
};

// products.js
const productsSDL = gql`
  type Query {
    allProducts: [Product]
  }

  type Product {
    id: ID!
    name: String!
  }
`;

const productsResolvers = {
  Query: {
    allProducts: () =&gt; callProductsDB()
  }
};


// “merging” types and resolvers
const server = new ApolloServer({
  typeDefs: [reviewsSDL, productsSDL],
  resolvers: [reviewsResolvers, productsResolvers]
});</code></pre>



<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 class="wp-block-paragraph">GraphQL is extremely flexible and a strong type system allows for lots of amazing tooling to be built. When you are choosing any library or coding pattern there will be trade-offs and decisions to be made, so taking the time to compare your tool set and your team&#8217;s needs will help you make an informed decision on what one to use. If you have any other misconceptions that you hear often about schema-first vs code-only share this article and tweet at us <a href="https://twitter.com/apollographql">@apollographql</a> with how you explain it in your own words!</p>


Schema-First vs Code-Only GraphQL


<p class="wp-block-paragraph">GraphQL is a popular language, and it&#8217;s getting more popular by the day. We hear front-end developers, mobile developers, and back-end developers talking about GraphQL. So it&#8217;s clear that developers use GraphQL across the stack. But where exactly does GraphQL fit in the stack, and what benefits do you gain by using it?</p>



<p class="wp-block-paragraph">In this article, we&#8217;ll first do a quick recap of what &#8220;the stack&#8221; looks like without GraphQL, and then we&#8217;ll dive into how adding GraphQL changes it and what that means for building applications.</p>



<h2 class="wp-block-heading"><a href="#the-stack-without-graphql" aria-hidden="true" class="aal_anchor" id="the-stack-without-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>The Stack Without GraphQL</h2>



<p class="wp-block-paragraph">An architecture without GraphQL will usually consist of three layers &#8211; the UI layer, the service layer, and the data layer. The specific structure of those three layers will look different depending on the size and needs of the company.</p>



<h3 class="wp-block-heading"><a href="#ui-layer" aria-hidden="true" class="aal_anchor" id="ui-layer"><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>UI Layer</h3>



<p class="wp-block-paragraph">The UI layer consists of all clients that interact with any backing APIs (the service layer). Including web apps, mobile apps, streaming devices, kiosks, etc.</p>



<h3 class="wp-block-heading"><a href="#data-layer" aria-hidden="true" class="aal_anchor" id="data-layer"><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>Data Layer</h3>



<p class="wp-block-paragraph">The data layer consists of all the data stores accessed by the service layer. Depending on the architecture of the service layer, the data layer could take on many forms.</p>



<h3 class="wp-block-heading"><a href="#service-layer" aria-hidden="true" class="aal_anchor" id="service-layer"><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>Service Layer</h3>



<p class="wp-block-paragraph">The service layer exposes one or more APIs to the UI layer. It can take on many different shapes, but for now, we&#8217;ll cover three common architectures:</p>



<ol class="wp-block-list"><li><strong>Client-to-service &#8211;</strong> The service layer consists of internal and external APIs exposed to the UI layer, creating a direct client-to-service relationship.</li><li><strong>API Gateway &#8211;</strong> The service layer consists of a single API that sits in front of other backing services. Clients interact only with the API Gateway.</li><li><strong>Backend-for-frontend</strong> &#8211; The service layer consists of multiple smaller APIs responsible for one or more clients that sit in front of other backing services.</li></ol>



<figure class="wp-block-image size-large is-resized"><img loading="lazy" decoding="async" src="https://wp.apollographql.com/wp-content/uploads/2021/10/service-layer-examples-1-1024x596.png" alt="Diagram of structure of full stack application with Client-to-Service architecture, API Gateway architecture, and Backend-for-Frontend (or BFF) architecture." class="wp-image-9778" width="610" height="355" srcset="https://wp.apollographql.com/wp-content/uploads/2021/10/service-layer-examples-1-1024x596.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/10/service-layer-examples-1-300x175.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/10/service-layer-examples-1-768x447.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/10/service-layer-examples-1.png 1200w" sizes="auto, (max-width: 610px) 100vw, 610px" /></figure>



<p class="wp-block-paragraph">While these architectures are functional, they fail to expose more capabilities to the UI layer without forcing more complexity on the clients. The constantly increasing number of endpoints makes managing communication with the service layer difficult. As the number of endpoints increases, the client&#8217;s ability to iterate decreases.</p>



<p class="wp-block-paragraph">The service layer often evolves into architectures like the API gateway and BFF patterns to prevent the clients from managing many endpoints. However, even with APIs explicitly built for a few or even a single client, they still have the problem of an increasing number of endpoints as the API surface grows.</p>



<p class="wp-block-paragraph">Adding GraphQL into the stack solves this problem. Let&#8217;s dive into what this means and closely examine how GraphQL changes the stack by introducing a new layer called <strong>the graph</strong>.</p>



<h2 class="wp-block-heading"><a href="#the-stack-with-graphql" aria-hidden="true" class="aal_anchor" id="the-stack-with-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>The Stack With GraphQL</h2>



<p class="wp-block-paragraph">GraphQL serves as the doorway into the graph layer. The graph layer fits in between the UI layer and the service layer. It brings all of a company&#8217;s data and services together into one consistent, secure, and discoverable interface so that anyone can access it through a single endpoint.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="596" src="https://wp.apollographql.com/wp-content/uploads/2021/10/graph-layer-example-1024x596.png" alt="Comparison between structure of full-stack application with REST architecture and full-stack application with GraphQL added. Structure now includes new Graph layer." class="wp-image-9780" srcset="https://wp.apollographql.com/wp-content/uploads/2021/10/graph-layer-example-1024x596.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/10/graph-layer-example-300x175.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/10/graph-layer-example-768x447.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/10/graph-layer-example.png 1200w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">Because the graph layer only exposes a single endpoint through GraphQL, it decouples the UI from changes further up the stack, and it will always remain a single endpoint, no matter how large the service layer and graph layer may get.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="596" src="https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-1024x596.png" alt="Diagram of application with growing Graph and Service Layer. Only one endpoint remains for each front-end app." class="wp-image-9783" srcset="https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-1024x596.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-300x175.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-768x447.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-1536x895.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-2048x1193.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-1200x699.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/10/mono-vs-unified-graph-1-1980x1153.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">Clients can now focus on building the product instead of building the infrastructure needed to manage all the endpoints from the service layer. Inversely, the service layer can evolve freely, without worrying about affecting clients.</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 class="wp-block-paragraph">Let&#8217;s return to the original question: where does GraphQL fit in the stack? We&#8217;ve uncovered that using GraphQL changes application architecture by adding the graph layer to the stack. So GraphQL does more than fit into an existing layer in the stack &#8211; it forms the foundation for a completely new layer.</p>



<p class="wp-block-paragraph">With the graph layer in place, clients can access what they need through a single endpoint. In addition, the reduced surface area allows developers on both the client and server sides to build independently, creating a more flexible architecture. If you&#8217;re interested in learning more about the benefits of using GraphQL instead of REST, take a look at this <a href="https://www.apollographql.com/blog/graphql/basics/graphql-vs-rest/">GraphQL vs. REST article</a>.</p>


Where Does GraphQL Fit In the Stack? Modern App Development with GraphQL title card

Where Does GraphQL Fit In the Stack? – Modern App Development with GraphQL


<p class="wp-block-paragraph">How do you debug or optimize a request as it travels through all the layers of your stack: from the client, through the Apollo Gateway, through your subgraph services, all the way to your databases?</p>



<p class="wp-block-paragraph">First, you need visibility into what your code is doing during that request, regardless of how that work is distributed across machines. Fortunately, this is easier than ever with a Cloud-Native Computing Foundation project called <a href="https://opentelemetry.io/">OpenTelemetry</a>!</p>



<p class="wp-block-paragraph">As of version 0.31.1, <a href="https://www.apollographql.com/docs/federation/api/apollo-gateway">@apollo/gateway</a> natively supports OpenTelemetry as part of a complete picture of the performance and reliability of a federated GraphQL request. You can find <a href="https://www.apollographql.com/docs/federation/opentelemetry/">the documentation here</a>.</p>



<p class="wp-block-paragraph">In this article, I’ll cover some OpenTelemetry basics, talk about the new support for OpenTelemetry in Apollo Gateway, and explain how Apollo Studio and OpenTelemetry work together to give you a complete picture of your graph.</p>



<h2 class="wp-block-heading"><a href="#what-is-opentelemetry" aria-hidden="true" class="aal_anchor" id="what-is-opentelemetry"><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 OpenTelemetry?</h2>



<p class="wp-block-paragraph">OpenTelemetry (or OTel) is “an observability framework for cloud-native software”. It is a collection of libraries, systems, and applications for instrumenting, collecting, and exporting information about workloads that span multiple applications.</p>



<p class="wp-block-paragraph">A unit of work in OTel is a “span”. You can wrap a function call in a span, recording its duration and other metadata. You can also install instrumentation that automatically hooks into modules and functions, like the <a href="https://www.npmjs.com/package/@opentelemetry/instrumentation-http">HTTP instrumentation</a> for Node.js.</p>



<p class="wp-block-paragraph">A collection of related spans is called a “trace”. In a single system, a trace is very similar to a stack trace. But what makes OpenTelemetry (and its predecessors, OpenTracing and OpenCensus) powerful is the ability to correlate spans across systems. It does this by propagating trace identifiers in remote calls. When making HTTP requests, for example, OTel instrumentation adds trace IDs as HTTP headers.</p>



<p class="wp-block-paragraph">Once you have a trace, you can aggregate them in a “collector” and efficiently send them to your observability tools with an “exporter”.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="605" src="https://wp.apollographql.com/wp-content/uploads/2021/07/OpenTelemetryApolloFederation-1024x605.png" alt="" class="wp-image-8203" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/OpenTelemetryApolloFederation-1024x605.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/OpenTelemetryApolloFederation-300x177.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/OpenTelemetryApolloFederation-768x454.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/OpenTelemetryApolloFederation.png 1144w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A diagram of a request flowing through a federated GraphQL architecture with OpenTelemetry and Apollo traces published to an OTel collector and Apollo Studio, respectively.</figcaption></figure>



<p class="wp-block-paragraph">There’s obviously a lot more to OpenTelemetry (<a href="https://opentelemetry.io/docs/concepts/what-is-opentelemetry/">see the docs!</a>), but that covers it in the context of Apollo Federation.</p>



<h2 class="wp-block-heading"><a href="#opentelemetry-in-apollo-server-and-apollo-gateway" aria-hidden="true" class="aal_anchor" id="opentelemetry-in-apollo-server-and-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>OpenTelemetry in Apollo Server and Apollo Gateway</h2>



<p class="wp-block-paragraph">Apollo Server has always supported OpenTelemetry via the <a href="https://www.npmjs.com/package/@opentelemetry/instrumentation-graphql">@opentelemetry/instrumentation-graphql</a> library, which instruments the underlying <a href="https://www.npmjs.com/package/graphql">graphql.js</a> library.</p>



<p class="wp-block-paragraph">However, Apollo Gateway doesn’t use graphql.js to execute a GraphQL request; instead, it executes a “query plan”, coordinating smaller requests to your subgraph services and assembling them into a single response. The Gateway executor has a few phases:</p>



<ul class="wp-block-list"><li>Validation</li><li>Planning</li><li>Execution</li><li>Fetching</li><li>Postprocessing</li></ul>



<p class="wp-block-paragraph">Apollo Gateway now instruments these phases as spans in an OTel trace. Combined with HTTP instrumentation, which propagates the trace ID as headers in requests to subgraphs, we can now connect the gateway query planning and execution to the actual GraphQL field resolution work in your subgraph services.</p>



<p class="wp-block-paragraph">Check out our <a href="https://www.apollographql.com/docs/federation/opentelemetry/#1-install-required-libraries">documentation on setting up OpenTelemetry</a> in your Apollo Gateway and Apollo Server apps.</p>



<p class="wp-block-paragraph">Even if you’re using GraphQL framework other than Apollo Server or a language other than JavaScript, you can still use OTel to instrument your application. There are OTel instrumentation libraries for many other languages and frameworks, and <a href="https://opentelemetry.io/registry/?s=graphql&amp;component=&amp;language=">GraphQL-specific OTel support</a> is small but growing.</p>



<h2 class="wp-block-heading"><a href="#opentelemetry-in-your-infrastructure" aria-hidden="true" class="aal_anchor" id="opentelemetry-in-your-infrastructure"><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>OpenTelemetry in your Infrastructure</h2>



<p class="wp-block-paragraph">Instrumenting a request is cool, but it’s not very useful on its own. You can export traces into many different systems to view, inspect, or search traces.</p>



<p class="wp-block-paragraph">The open-source projects Zipkin and Prometheus both support OpenTelemetry. Here’s an example of a federated GraphQL request in Zipkin.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="567" src="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-1024x567.png" alt="" class="wp-image-8205" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-1024x567.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-300x166.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-768x425.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-1536x850.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-2048x1134.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-1200x664.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-23-at-9.55.49-AM-1980x1096.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A screenshot of a trace in the Zipkin web UI, showing spans for the gateway and multiple subgraphs.</figcaption></figure>



<p class="wp-block-paragraph">The OpenTelemetry project has a number of exporters for various Application Performance Monitoring (APM) tools, including SaaS products like Datadog and Honeycomb, or cloud provider solutions like AWS X-Ray. You can find a complete list in the <a href="https://opentelemetry.io/registry/?s=&amp;component=exporter&amp;language=">OpenTelemetry Registry</a>.</p>



<h2 class="wp-block-heading"><a href="#opentelemetry-doesnt-replace-apollo-tracing" aria-hidden="true" class="aal_anchor" id="opentelemetry-doesnt-replace-apollo-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>OpenTelemetry doesn’t replace Apollo Tracing</h2>



<p class="wp-block-paragraph">OpenTelemetry is great at recording what happened, but it doesn’t tell you much about what <em>could</em> happen. Apollo Studio uses the declarative nature of GraphQL to help you catch potential errors before they happen. Consider this GraphQL operation:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">query ProductsPage($categoryId: ID!) {
  products(category: $categoryId) {
    nodes {
      sku
      price
      reviews { # could return null
        nodes {
          id
          body
          rating
          author {
            name
            photoUrl 
          }
        }
      }
    }
  }
}</code></pre>



<p class="wp-block-paragraph">If the <code class="" data-line="">Product.reviews</code> field returns null, then the GraphQL executor won’t run resolvers for any of the fields nested inside that selection like <code class="" data-line="">Review.id</code>, <code class="" data-line="">Review.body</code>, or <code class="" data-line="">Author.name</code>. OTel instrumentation won’t record any spans, so you’ll have no data about those fields.</p>



<p class="wp-block-paragraph">However, if you remove or change the <code class="" data-line="">Author.name</code> field, you could break all the clients that include that field in their operations.</p>



<p class="wp-block-paragraph">We designed <a href="https://www.apollographql.com/docs/federation/metrics/">Apollo Federated Tracing</a> to collect field usage regardless of what actually happens (or doesn’t happen!) in your services. Our tracing data powers the <a href="https://www.apollographql.com/docs/studio/schema-checks/">Schema Checks</a> feature, alerting you of potentially breaking changes and giving you confidence as you evolve your API.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="638" src="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-1024x638.png" alt="" class="wp-image-8207" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-1024x638.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-300x187.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-768x478.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-1536x957.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-2048x1276.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-1200x748.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.53.37-AM-1980x1233.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A screenshot of a failed check in Apollo Studio.</figcaption></figure>



<p class="wp-block-paragraph">Apollo Studio also knows schema-related information like the <code class="" data-line="">@deprecated</code> directive, so we can help you understand how clients are using deprecated fields.</p>



<figure class="wp-block-image size-large is-resized"><img loading="lazy" decoding="async" src="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM-1024x210.png" alt="" class="wp-image-8209" width="610" height="125" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM-1024x210.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM-300x62.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM-768x158.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM-1536x316.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM-1200x247.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.50.03-AM.png 1732w" sizes="auto, (max-width: 610px) 100vw, 610px" /><figcaption>A screenshot of deprecation information in Apollo Studio.</figcaption></figure>



<p class="wp-block-paragraph">It’s possible to cross-reference OTel traces and Apollo Studio traces by customizing the <a href="https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting/">Usage Reporting plugin</a> in Apollo Server. By passing header values in trace sent to Studio that align with attributes on your OTel spans, you can jump between Studio and your OTel observability tooling to get a complete picture of a request.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="572" src="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-1024x572.png" alt="" class="wp-image-8211" srcset="https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-1024x572.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-300x168.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-768x429.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-1536x858.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-2048x1144.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-1200x670.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/07/Screen-Shot-2021-07-22-at-10.52.54-AM-1980x1106.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A screenshot of a trace in Apollo Studio with metadata you can use to associate this request with an OpenTelemetry trace.</figcaption></figure>



<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 class="wp-block-paragraph">OpenTelemetry is a fantastic open-source project and we’re excited to participate in the growing ecosystem. Combined with Apollo Studio, OpenTelemetry gives you a clear picture of your running systems, helping you debug, optimize, and evolve your federated graphs.</p>



<p class="wp-block-paragraph">Check out the <a href="https://opentelemetry.io/docs/">OpenTelemetry documentation</a> and our <a href="https://www.apollographql.com/docs/federation/opentelemetry/">documentation on instrumenting federated graphs</a>.</p>


Introducing Open Telemetry for Apollo Federation


<p class="wp-block-paragraph">Most organizations&#8217; adventures with GraphQL start with one team looking for a way to solve one of the most significant frontend development problems in a microservice architecture: how to get all the data your app needs without making a million and one service calls.</p>



<p class="wp-block-paragraph">For a frontend engineer, that promise of getting all the data they need, in the&nbsp;<em>exact shape they envision using it</em>&nbsp;(and with only a single request) is often too hard to resist.</p>



<p class="wp-block-paragraph">It&#8217;s here where a proof of concept comes to fruition. The POC proves the hypothesis that it 1) simplifies the codebase and 2) increases team velocity. Before you know it, GraphQL is in production.&nbsp;</p>



<p class="wp-block-paragraph">The organization now has its first GraphQL API, but where does it go from there? The answer to that question depends on the organization: how they&#8217;ve structured their product engineering teams, the desired level of self-sufficiency of teams, their adherence to the ideals of a distributed architecture, etc.</p>



<p class="wp-block-paragraph">In this blog post, I will walk you through your options for evolving GraphQL at your organization, from monoliths to BFFs to Federation.</p>



<h2 class="wp-block-heading"><a href="#a-fork-in-the-road" aria-hidden="true" class="aal_anchor" id="a-fork-in-the-road"><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 Fork in the Road</h2>



<p class="wp-block-paragraph">With a working GraphQL API in place, it won&#8217;t be long before other teams want to use it and get all the benefits of using GraphQL.</p>



<p class="wp-block-paragraph">Things tend to go in one of two directions: teams either start to adopt and add to the existing implementation (monolith) or duplicate what the initial team has done (BFF).</p>



<h3 class="wp-block-heading"><a href="#the-glorious-monolith" aria-hidden="true" class="aal_anchor" id="the-glorious-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 Glorious Monolith</h3>



<p class="wp-block-paragraph">Rather than reinvent the wheel, other teams want to build onto the efforts of that first team. Initially, things start great with new teams adding their unique data concerns to the graph and reusing the rest&#8217;s pre-existing schema.</p>



<p class="wp-block-paragraph">Product development times decrease, there&#8217;s less duplication of effort, frontend engineers have a consistent API tailored to them to work with, etc. Nirvana, right? Not so quick.</p>



<p class="wp-block-paragraph">As with any other type of monolithic application, as they grow, the cracks start to appear. The more teams there are making changes to it, the harder it is to release change, and, before you know it, the dream becomes a nightmare and our monolithic GraphQL API becomes a hated beast.</p>



<p class="wp-block-paragraph">Also, the odds are that the initial implementation only considered the&nbsp;<strong>implementing team&#8217;s data needs</strong>&nbsp;and&nbsp;<em>their product.&nbsp;</em>This means the initial types and schemas are likely to have been structured around the initial team&#8217;s access patterns, which are likely to differ from others&#8217;.</p>



<p class="wp-block-paragraph">Take an eCommerce application as an example. The team building product listings want to access product information by requesting products with a specific SKU, but the team building the basket will want product details for only those product SKUs contained within the basket.</p>



<p class="wp-block-paragraph">This is a very simplistic example and easily fixable, but, in a monolithic implementation, it&#8217;s likely that both teams would write their own resolvers, probably duplicating the fetching logic for the back service that provides the product data.</p>



<p class="wp-block-paragraph">Suddenly we start getting duplication of effort again, and things start to get messier by the day.</p>



<h3 class="wp-block-heading"><a href="#backend-for-frontend" aria-hidden="true" class="aal_anchor" id="backend-for-frontend"><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>Backend for Frontend</h3>



<p class="wp-block-paragraph">Rather than building on the initial implementation, another common approach is to follow the backend for frontend (BFF) pattern and introduce a GraphQL server per experience (either an app, channel, team, page, etc.) that only handles the data needs of that experience.</p>



<p class="wp-block-paragraph">With BFF, we tailor each BFF&#8217;s schema around the experience&#8217;s access patterns and mirror the frontend application&#8217;s needs. It feels like we are getting closer to that nirvana state, right?</p>



<p class="wp-block-paragraph">In some cases, yes, but consider what we are doing here: we are creating a GraphQL BFF&nbsp;<em>per experience</em>&nbsp;with the potential for a lot of duplication amongst BFFs.</p>



<p class="wp-block-paragraph">In an organization with teams that have a very narrow focus (say where an experience is equivalent to a page on a site), there will be&nbsp;<strong>a lot</strong>&nbsp;of duplicated functionality. Not only that, but infrastructure costs will go up, and the number of attack vectors increases, among other things.</p>



<p class="wp-block-paragraph">That said, BFFs can be a highly effective way of introducing and using GraphQL within organizations. Depending on the app you are building and your organizational structure, this may indeed be your end game.</p>



<p class="wp-block-paragraph">Michelle Garrett gives a <a href="https://youtu.be/qaQEioKovCg">great talk</a> on how Condé Nast makes effective use of BFFs that I&#8217;d highly recommend you check out as an example of running the BFF pattern at scale.</p>



<p class="wp-block-paragraph">But it is not for everyone.</p>



<p class="wp-block-paragraph">Let&#8217;s switch gears and talk about a different approach.</p>



<h2 class="wp-block-heading"><a href="#one-gateway-to-rule-them-all" aria-hidden="true" class="aal_anchor" id="one-gateway-to-rule-them-all"><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>One Gateway to Rule Them All</h2>



<p class="wp-block-paragraph">So what are the alternatives to a single monolith or numerous BFFs? For a long time, the only option available to teams was schema stitching.</p>



<p class="wp-block-paragraph"><a href="https://www.apollographql.com/docs/federation/migrating-from-stitching/">Schema stitching</a> describes the process of creating a single GraphQL schema from multiple underlying GraphQL schemas. It was a technique designed to solve some of the challenges faced by those who went down the monolithic GraphQL route.</p>



<p class="wp-block-paragraph">It essentially allows you to split up and distribute a monolithic GraphQL schema into several underlying services. Each of these deals with one or more types of the original schema. In front of these, you place a gateway server that will use tooling to introspect and build up a singular schema from the individual parts.</p>



<p class="wp-block-paragraph">When a request comes into the gateway, it acts as a proxy and distributes the query amongst the underlying services. So, requests for type A will be sent to service A, type B to service B, etc.</p>



<p class="wp-block-paragraph">But schema stitching isn&#8217;t easy.</p>



<p class="wp-block-paragraph">Using my simple example of Product and Basket types, what you want is the following schema where the <code class="" data-line="">Basket</code> type contains an items field that returns an array of <code class="" data-line="">Product</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line=""># Product service
type Product {
  id: ID!
  name: String
  description: String
}
​
# Basket service 
type Basket {
  id: ID!
  items: [BasketItem]
}
​
type BasketItem {
  id: ID!
  quantity: Int
  product: Product
}
​
# Query to fetch the basket
query {
  getBasket(id: 12345) {
    items {
      id
      quantity
      product {
        name
        description
      }
    }
  }
}</code></pre>



<p class="wp-block-paragraph">​But that won&#8217;t work. The <code class="" data-line="">Basket</code> service has no knowledge of <code class="" data-line="">Products</code> and probably only knows about the ID of the products in the basket.</p>



<p class="wp-block-paragraph">Exposing the schema gets messy. You&#8217;d either have to:</p>



<ul class="wp-block-list"><li>Use some glue code in the gateway. It will need to understand the relationship between the two services and do a behind-the-scenes fetch of all Products that match the IDs held in BasketItems.</li><li>Or instead, make the <code class="" data-line="">Basket</code> service call the <code class="" data-line="">Product</code> service to get the <code class="" data-line="">Product</code> information.</li></ul>



<p class="wp-block-paragraph">Of course, this would be invisible to the consumer of the stitched schema, but… don&#8217;t you feel just a little bit dirty having read the past few paragraphs? As a one-off, it is fine, but multiply this by however many interconnections you have between your types and… eek!</p>



<p class="wp-block-paragraph">Schema stitching is full of these little solvable problems, but it is&nbsp;<em>death by a thousand cuts</em>. Throw into the mix questions on updating the stitched schema when one of the underlying schemas change or what happens when one of the underlying services is down at compose time. I guarantee you will quickly be banging your head against your desk.</p>



<h2 class="wp-block-heading"><a href="#federation-to-the-rescue" aria-hidden="true" class="aal_anchor" id="federation-to-the-rescue"><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>Federation to the Rescue</h2>



<p class="wp-block-paragraph">So what to do? A monolith is bad because monoliths are bad, BFFs are great, but the amount of duplication can get ridiculous at scale, and schema stitching is… a headache and often very fragile.</p>



<p class="wp-block-paragraph">In an attempt to solve this dilemma, Apollo <a href="https://www.youtube.com/watch?v=LKQKn1oFXJU&amp;ab_channel=ApolloGraphQL">introduced Apollo Federation in May 2019</a> to give the ability to build a single, cohesive schema from multiple federated services.</p>



<p class="wp-block-paragraph">Rather than splitting the schema up by type (which you end up doing with schema stitching), federation allows you to separate it by&nbsp;<em>concern</em>.​</p>



<p class="wp-block-paragraph">I won&#8217;t go into too much detail here (I&#8217;ll save that for a later blog post), but it does this by allowing multiple federated services to extend a single type, with the gateway composing the type fragments together again.</p>



<p class="wp-block-paragraph">The gateway&#8217;s inbuilt query planner then splits incoming queries into smaller queries (based on its understanding of which service resolves which part of the query) and sends them on to the federated services.</p>



<p class="wp-block-paragraph">Refactoring our example from earlier:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line=""># Basket service 
type Basket @key(fields: &quot;id&quot;) {
  id: ID!
  items: [BasketItem]
}
​
type BasketItem {
  id: ID
  quantity: Int
}
​
# Product service
type Product @key(fields: &quot;id&quot;) {
  id: ID!
  name: String
  description: String
}
​
extend type BasketItem @key(fields: &quot;id&quot;) {
  id: ID! @external
  product: Product
}
​
# Query to fetch the basket
query {
  getBasket(id: 12345) {
    items {
      id
      quantity
      product {
        name
        description 
      }
    }
  }
}</code></pre>



<p class="wp-block-paragraph">The Basket service defines a <code class="" data-line="">Basket</code> type with an items field of <code class="" data-line="">BasketItem</code> that defines the quantity of a given item. But where are the products?</p>



<p class="wp-block-paragraph">Well, the Product service now not only defines the <code class="" data-line="">Product</code> type, but it also extends the <code class="" data-line="">BasketItem</code> defined in the Basket service. It also adds a product field that resolves the related product for that given basket item.</p>



<p class="wp-block-paragraph">How does it achieve this? At a high level, the <code class="" data-line="">@key</code> directives after the various types define the externally referenceable fields used to link the types together.</p>



<p class="wp-block-paragraph">One of the easiest ways I&#8217;ve found to reason about this is to think of the federated data graph as a relational database, with the keys being analogous with foreign keys in the database. Each federated service then needs to provide a standard resolver to handle queries referencing their foreign key(s).</p>



<p class="wp-block-paragraph">In the above simple example, each federated service now only has to be <em>concerned</em> about one high-level data type. The Basket service handles all requests for <code class="" data-line="">Basket</code> data and the Product service handles all requests for <code class="" data-line="">Product</code> data, even when some of those requests are&nbsp;<em>actually</em>&nbsp;made to resolve the <code class="" data-line="">Product</code> data for the items in the <code class="" data-line="">Basket</code>.</p>



<p class="wp-block-paragraph">This fits in nicely with the modern trend for microservice architectures with colocated data sources. There are no blurred lines between services or, say, the Basket service storing a subset of product data for items in the <code class="" data-line="">Basket</code>.</p>



<p class="wp-block-paragraph">Is it perfect? No, and running a large federated data graph comes with a whole host of distributed system challenges, but it is a giant step forward for GraphQL at scale.</p>



<p class="wp-block-paragraph">Thanks for reading; if you&#8217;d like to talk GraphQL or tech in general, give me a follow on <a href="https://twitter.com/andyroberts_io">Twitter</a> and send me a DM. As a bonus, you&#8217;ll also get to see any future blogs I write!</p>



<p class="wp-block-paragraph"></p>


the evolution of graphql at scale by andy roberts

The Evolution of GraphQL at Scale


<p class="wp-block-paragraph">The reality for most large organizations adopting Federation is that the architecture sitting behind it is… messy. In this article, I will introduce the concept of <em>schema services</em> and demonstrate how they can provide an easier transition towards a federated architecture.</p>



<p class="wp-block-paragraph">From a jumble of modern and legacy services, different tech stacks, data sources, platforms, etc. most enterprise architecture diagrams look more like a <em>grab bag</em> of tech from the last couple of decades than anything else. It most definitely doesn’t look like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="219" src="https://wp.apollographql.com/wp-content/uploads/2020/11/image.png" alt="Transitioning-towards-a-federated-architecture-1-1-1024x219.png" class="wp-image-5589" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/image.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/image-300x64.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/image-768x164.png 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">It’s all very well seeing diagrams that show the perfect end state of a gateway backed by a set of federated services (like the one above), but, while that makes for a great target, it begs the question: what does a transitionary architecture look like?<br></p>



<p class="wp-block-paragraph">Further complicating matters is another reality that most organizations face: a lack of GraphQL skills in their engineering teams. GraphQL is still a relatively new technology, and many engineers have little to no experience of GraphQL yet. How do you rapidly rollout Federation when you have a significant skills gap?<br></p>



<p class="wp-block-paragraph">I believe the answer is a <em>transitionary</em> architecture.</p>



<h2 class="wp-block-heading"><a href="#focus-on-a-transitionary-architecture" aria-hidden="true" class="aal_anchor" id="focus-on-a-transitionary-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>Focus on a Transitionary Architecture</h2>



<p class="wp-block-paragraph">While implementing Apollo Federation at <a href="https://www.rs-online.com/">RS Components</a>, we had to develop a transitionary architecture that could overcome both the messy architectural landscape and the GraphQL skills gap in our engineering teams.<br></p>



<p class="wp-block-paragraph">We started our implementation a year or so into a multi-year project to migrate our monolithic application (which is 20+ years old) to a cloud-based microservices architecture. At the start of the project, only about 20% of the data was available from these new services; the rest coming from legacy systems.</p>



<p class="wp-block-paragraph">Across both the old and new services, the APIs were more data-centric than product-centric and contained lots of internal language that external consumers would not understand. In order to create a product-focused schema, we would either have to update the services or transform the data being returned.<br></p>



<p class="wp-block-paragraph">Further complicating the situation was the mix of protocols being used across the various services: most were REST based, with a sprinkling of GraphQL-native ones along with some which were… unique to RS. Whilst our intent was (and still is) to shift all services over time to be GraphQL-native, for the foreseeable future we were going to be left with a variety of service types.<br></p>



<p class="wp-block-paragraph">Unsurprisingly there was neither capacity nor appetite for updating every service, so we had to come up with a solution that would not only allow us to create the product-focussed federated schema we wanted, but that would also act as a stepping stone towards the clean target architecture above.</p>



<h2 class="wp-block-heading"><a href="#introducing-schema-services" aria-hidden="true" class="aal_anchor" id="introducing-schema-services"><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>Introducing Schema Services</h2>



<p class="wp-block-paragraph">Our solution to this problem was to introduce a set of services in between the gateway and our underlying services: we call these <em>schema services</em>.<br></p>



<p class="wp-block-paragraph">A <strong>schema service</strong> deals with a single <em>concern</em>, combining and transforming several microservice responses into a single, product-focused schema. Taking and updating the simple diagram from earlier, we now have:<br></p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="317" src="https://wp.apollographql.com/wp-content/uploads/2020/11/image-1.png" alt="image.png" class="wp-image-5593" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/image-1.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/image-1-300x93.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/image-1-768x238.png 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">In the above we have introduced two <strong>schema services</strong>: <code class="" data-line="">Product</code> and <code class="" data-line="">Customer</code>. These sit between our federated gateway and the underlying services, responding to incoming operations from the gateway for their given concern.</p>



<p class="wp-block-paragraph">Schema services are kept intentionally slim and are typically nothing more than an <a href="https://www.apollographql.com/docs/apollo-server/">Apollo Server</a> instance containing a schema that is backed by simple resolvers that make use of custom <a href="https://www.apollographql.com/docs/apollo-server/data/data-sources/">data sources</a> to call the underlying services. These data sources bake in standardized logging, caching and transformation hooks in order to reduce duplication of code between services.</p>



<p class="wp-block-paragraph">With the introduction of schema services, underlying services can now be made available through the federated gateway with no changes required to the services at all. Rather than facing an uphill battle to convert all our services, we now only have to introduce a handful of schema services in order to create our federated data graph &#8211; we currently have eight schema services at RS.</p>



<h3 class="wp-block-heading"><a href="#baby-steps-towards-the-target" aria-hidden="true" class="aal_anchor" id="baby-steps-towards-the-target"><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>Baby Steps Towards the Target</h3>



<p class="wp-block-paragraph">The <code class="" data-line="">Review</code> service in the diagram above is an example of how schema services can be phased out of our transitionary architecture. When the team that owns a service is able to take on the work of federating their service, as in the case of the <code class="" data-line="">Review</code> service, then they can be integrated into the gateway directly.</p>



<p class="wp-block-paragraph">This gradual move to directly federated services will slowly transition us towards our target architecture and eventually mean that the schema services are redundant.<br></p>



<h3 class="wp-block-heading"><a href="#advantages-of-this-approach" aria-hidden="true" class="aal_anchor" id="advantages-of-this-approach"><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>Advantages of This Approach</h3>



<ul class="wp-block-list"><li>There is no impact on existing services, the schema services will call them like any other client.</li><li>The federated schema can start small and grow as more data requirements are included.</li><li>Schema services are relatively simple services with no business logic. They should be quick to develop, test and release.</li><li>If desirable, the initial schema service development can be centralized in one team meaning there are no inter-team dependencies to complicate matters.</li><li>Further more, schema services can remain centralized if so desired to allow for a highly controlled schema.</li><li>Federatable schemas can be designed from scratch without having to accommodate legacy or data-centric language.</li><li>Schema service caching can be used to limit traffic to the underlying services, especially helpful when protecting legacy systems.</li></ul>



<h3 class="wp-block-heading"><a href="#disadvantages-of-this-approach" aria-hidden="true" class="aal_anchor" id="disadvantages-of-this-approach"><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>Disadvantages of This Approach</h3>



<ul class="wp-block-list"><li>There is an additional hop in all requests for data; this will add latency to requests and complicate the overall architecture.</li><li>No matter which way you look at it, you are introducing additional services into your architecture and thus cost.</li><li>Synchronising changes in the schema services with underlying service changes mean that there is coupling between the two layers. Depending on the rate of change, this can be a big headache.</li><li>Ownership of schema services can become complex. If you start centralised and then distribute ownership later, how is that transition managed? What’s the governance model and how do you maintain schema consistency.</li></ul>



<h2 class="wp-block-heading"><a href="#summary" aria-hidden="true" class="aal_anchor" id="summary"><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>Summary</h2>



<p class="wp-block-paragraph">Are schema services perfect? No, not by a long shot, but they do turn what at first seems a daunting task of federating a messy collection of services, legacy systems and whatever other dragons are hiding in your enterprise into a manageable project that can be delivered in a surprisingly short amount of time.</p>



<p class="wp-block-paragraph">My only advice, no matter what approach you take, is to start small.</p>



<p class="wp-block-paragraph">Most enterprises have a lot of data and a lot of services, so pick a subset of both and deliver Federation for a single page or feature to start with. Keep a narrow focus.</p>



<p class="wp-block-paragraph">Thanks for reading; if you’d like to talk about schema services, GraphQL or tech in general, give me a follow on <a href="https://twitter.com/andyroberts_io">Twitter</a> and send me a DM. As a bonus, you’ll also get to see any future blogs I write!</p>


Schema Services: Transitioning Towards a Federated Architecture


<p class="wp-block-paragraph"><a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL</a>’s value proposition for full-stack and frontend developers is pretty clear.&nbsp;<a href="https://medium.com/apollo-stack/why-graphql-is-the-future-3bec28193807" target="_blank" rel="noreferrer noopener">It provides the missing layer of abstraction between backends and frontends</a>. GraphQL is incredibly easy to use on the client, but writing a good GraphQL server can be a bit more work, and can sometimes be tricky.</p>



<p class="wp-block-paragraph">Having built a couple of GraphQL servers while working on&nbsp;<a href="https://github.com/apollostack" target="_blank" rel="noreferrer noopener">Apollo</a>, I thought it would be useful to do a writeup about a of the lessons I learned along the way.</p>



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



<h2 class="wp-block-heading" id="f4a5"><a href="#1-optimize-human-time-not-machine-time" aria-hidden="true" class="aal_anchor" id="1-optimize-human-time-not-machine-time"><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. Optimize human time, not machine time</h2>



<p class="wp-block-paragraph">One of the first traps I fell into was trying to optimize performance before I’d written a single line of code. Having worked with SQL backends before, my first question with GraphQL was:</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>“How do I make GraphQL send a JOIN query to my SQL database?”</p></blockquote>



<p class="wp-block-paragraph">It took me a while to realize that that question was the wrong question to be asking. I was trying to solve problems that I hadn’t even observed yet!&nbsp;Premature optimization is one of the cardinal sins of programming, and I was guilty of it. Instead of sticking to the clean abstraction that GraphQL gave me, I tried to optimize performance by making a single request to the DB. That made the code very hard to read and impossible to maintain.</p>



<p class="wp-block-paragraph">When I finally stopped trying to optimize performance that I hadn’t even measured yet, I realized that sticking to one query per resolver actually optimized a far more important parameter: how many hours I spent writing and rewriting code every time the API changed.</p>



<p class="wp-block-paragraph">It turns out that it doesn’t matter very much if your code isn’t the fastest, because scaling a cluster of GraphQL servers is easy. If you can cut the engineering time in half by running twice as many servers, you’d be stupid not to do that.</p>



<p class="wp-block-paragraph">Reducing the time spent on building and maintaining software largely comes down to choosing the right abstractions, and that’s no different in GraphQL. I highly recommend reading David Parnas’ fantastic paper “<a href="https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf" target="_blank" rel="noreferrer noopener">On the Criteria To Be Used in Decomposing Systems into Modules</a>”, if you haven’t already read it.</p>



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



<h2 class="wp-block-heading" id="c34c"><a href="#2-choose-the-right-abstractions" aria-hidden="true" class="aal_anchor" id="2-choose-the-right-abstractions"><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. Choose the right abstractions</h2>



<p class="wp-block-paragraph">Out of the box, GraphQL provides you with two abstractions: a&nbsp;<a href="https://medium.com/apollo-stack/graphql-explained-5844742f195e" target="_blank" rel="noreferrer noopener"><strong>schema</strong></a>&nbsp;and&nbsp;<a href="https://medium.com/apollo-stack/graphql-explained-5844742f195e" target="_blank" rel="noreferrer noopener"><strong>resolvers</strong></a>.</p>



<p class="wp-block-paragraph">The first layer of abstraction is provided by the GraphQL schema. It hides the details of the backend architecture from the frontend. The schema can even be written in GraphQL schema language, making it quite concise and easy to read or maintain. The most important decision at this layer is choosing which types and fields to create. This is specific to each application, but there are some general rules you can follow. For the sake of brevity I’ll skip them here, but if you’re interested, watch out for a future post on our&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">GraphQL blog</a>.</p>



<p class="wp-block-paragraph">Resolvers — also called resolve functions — are the second layer of abstraction. They define how the data for a field in a query is actually fetched, i.e. how the field is “resolved”. In order to let a schema map to any number of backends, GraphQL needs to be very flexible. The schema itself is tightly constrained, so all that flexibility has to be in the resolvers.</p>



<p class="wp-block-paragraph">Resolvers can contain arbitrary code, so being the lazy person I am, I first stuffed everything into the resolvers: data fetching, authorization, session management. As you can probably guess, it wasn’t readable nor maintainable. It was a bit quicker to write at first, but soon I hit the tipping point where I wasted more time making changes in half a dozen places for a minor change in the schema.</p>



<p class="wp-block-paragraph">Things looked a lot better when I started using two more abstractions: models and connectors.</p>



<h2 class="wp-block-heading" id="d5fa"><a href="#3-structure-your-code-with-models-and-connectors" aria-hidden="true" class="aal_anchor" id="3-structure-your-code-with-models-and-connectors"><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. Structure your code with Models and Connectors</h2>



<p class="wp-block-paragraph"><strong>Model:</strong>&nbsp;a set of functions to read/write data of a certain GraphQL type by using various connectors. Models contain additional business logic, such as permission checks, and are usually application-specific.</p>



<p class="wp-block-paragraph"><strong>Connector:</strong>&nbsp;a layer on top of a database/backend driver that has GraphQL-specific error handling, logging, caching and batching. Only needs to be implemented once for each backend, and can be reused in many apps</p>



<p class="wp-block-paragraph">By using models and connectors, my resolvers turned into simple switches that map inputs and arguments to a function call in the underlying model layer, where the actual business logic resides.</p>



<p class="wp-block-paragraph">Note: To be clear, models and connectors aren’t abstractions that are built into GraphQL, but they emerge as a natural way to structure code in a GraphQL server.</p>



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



<p class="wp-block-paragraph">It’s easiest to explain things with an example, so let’s take the&nbsp;<em>Author</em>&nbsp;and&nbsp;<em>Post</em>&nbsp;models from our&nbsp;<a href="https://medium.com/apollo-stack/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener">GraphQL tutorial</a>&nbsp;to show how it works in practice:</p>



<p class="wp-block-paragraph">Data for the fields of&nbsp;<em>Authors</em>&nbsp;and&nbsp;<em>Posts</em>&nbsp;is stored in a MySQL database, except for the&nbsp;<em>views&nbsp;</em>field of&nbsp;<em>Post</em>, which is stored in MongoDB.</p>



<p class="wp-block-paragraph">Instead of writing all the code directly in the resolvers, it makes sense to define two models — one for&nbsp;<em>Author</em>&nbsp;and one for&nbsp;<em>Post,&nbsp;</em>and use two connectors — one for MySQL and one for MongoDB.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1002" height="605" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Rru6xUfpG8HDh0YRnzJCew.png" alt="" class="wp-image-227" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Rru6xUfpG8HDh0YRnzJCew.png 1002w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Rru6xUfpG8HDh0YRnzJCew-300x181.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Rru6xUfpG8HDh0YRnzJCew-768x464.png 768w" sizes="auto, (max-width: 1002px) 100vw, 1002px" /><figcaption>Models are application-specific, while connectors are per-backend and can be shared across applicaitions</figcaption></figure>



<p class="wp-block-paragraph">As the diagram above shows, the&nbsp;<em>Post</em>&nbsp;model uses more than one connector, because the data for that type is stored in two different backends.</p>



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



<p class="wp-block-paragraph">Here’s an example of what it could look like in actual code.</p>



<p class="wp-block-paragraph">Resolver:</p>



<pre class="wp-block-preformatted">import { PostModel } from './models';<br>const resolvers = {<br>  Authors: {<br>    posts(author, args, context) {<br>      return PostModel.findByAuthor(author.id, context);<br>    },<br>  },<br>// ...<br>};</pre>



<p class="wp-block-paragraph">Model:</p>



<pre class="wp-block-preformatted">const models = {<br>  PostModel: {<br>    findByAuthor(authorId, context){<br>      context.mysql.raw(<br>        'SELECT * FROM posts WHERE authorId = ?',<br>        authorId,<br>      );<br>    },<br>    getViews(postId){<br>      return context.mongo.collection('views').find({postId});<br>    },<br>    // ...<br>  }<br>};  </pre>



<p class="wp-block-paragraph">A simple mongo connector:</p>



<pre class="wp-block-preformatted">class MongoConnector {<br>  constructor(connection){<br>    this.connection = connection;<br>  }  closeConnection(){<br>    this.connection.close();<br>  }  collection(collectionName){<br>    // caching, batching and logging could be added here<br>    return connection.collection(connectionName);<br>  }<br>}</pre>



<p class="wp-block-paragraph">And here’s how the server would be initialized:</p>



<pre class="wp-block-preformatted">// other imports ...// setting up DB connections etc.import schema from './schema';<br>import resolvers from './resolvers';<br>import {<br>  MongoConnector,<br>  MySQLConnector,<br>} from './connectors';app.use('/graphql', req =&gt; {<br>  const mongo = new MongoConnector(mongoConnection);<br>  const mysql = new MySQLConnector(mysqlConnection);<br>  return {<br>    schema,<br>    resolvers,<br>    context: {<br>      conn: {<br>        mongo,<br>        mysql,<br>      },<br>    },<br>  };<br>});// ...</pre>



<p class="wp-block-paragraph">For a more complete (and more complicated) example, check out our&nbsp;<a href="https://github.com/apollostack/GitHunt" target="_blank" rel="noreferrer noopener">GitHunt</a>&nbsp;demo app. It uses models and connectors in the way described here, and it also has a nice example of how to cache and batch requests to the GitHub API with a library called&nbsp;<a href="https://github.com/facebook/dataloader" target="_blank" rel="noreferrer noopener">dataloader</a>.</p>



<p class="wp-block-paragraph"><em>Note: If you want to use an ORM like Sequelize or Mongoose, that’s also a decent way to get started. In that case, the ORM takes care of both the model and the connector. Our&nbsp;</em><a href="https://medium.com/apollo-stack/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener"><em>server tutorial is probably the most complete example out there</em></a><em>.</em></p>



<h2 class="wp-block-heading" id="970c"><a href="#4-dont-fly-blind-measure-twice-code-once" aria-hidden="true" class="aal_anchor" id="4-dont-fly-blind-measure-twice-code-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>4. Don’t fly blind — measure twice, code once</h2>



<p class="wp-block-paragraph">Once I was reasonably happy with the structure of my GraphQL server, I was ready to optimize performance.</p>



<p class="wp-block-paragraph">Remember my earlier question: “How do I make GraphQL send a JOIN query to my SQL database?”. Now I actually knew enough to answer the question:</p>



<p class="wp-block-paragraph"><strong>The short answer is</strong>: you don’t. Use caching and batching instead.</p>



<p class="wp-block-paragraph"><strong>The longer answer is</strong>: You can do it, but it comes with a heavy cost to readability and maintainability, and&nbsp;<a href="http://stackoverflow.com/questions/1369136/orm-select-n-1-performance-join-or-no-join" target="_blank" rel="noreferrer noopener">it’s up for debate whether JOINs are actually faster than smaller queries that are efficiently batched and cached</a>.</p>



<p class="wp-block-paragraph">You should&nbsp;<strong>never</strong>&nbsp;<strong>optimize performance before you’ve measured performance</strong>, and that is true in this case as well. There are so many factors involved — CPU load, memory consumption, latency to DB, HTTP vs HTTP2, database engine, etc. — that’s it’s very hard to make an accurate guess as to what issues you’ll run into at scale. If you optimize A and it turns out that B was the real bottleneck, you’ve just wasted a bunch of time and made your code harder to read, without any actual benefit.</p>



<p class="wp-block-paragraph">Okay, so how do you measure performance? GraphQL endpoints are much more complex than REST endpoints, so just measuring how long it takes for queries to complete doesn’t give you an accurate enough picture. It might tell you that you have a problem, but it won’t tell you where your problem is at.</p>



<p class="wp-block-paragraph">In order to know which parts of your server are slow, you need to instrument individual resolve functions. Conventional profiling and performance monitoring tools don’t really give you a good picture of what’s going on in the server, so we put our heads together and built a custom GraphQL tracer. Even though it’s still under active development, it has already helped us and others find and fix bottlenecks and performance issues in our GraphQL servers, which we would have not found otherwise!</p>



<p class="wp-block-paragraph">Here’s one of the screens, showing a partial trace of a slow GraphQL request:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="676" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-1024x676.png" alt="" class="wp-image-226" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-1024x676.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-300x198.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-768x507.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-1536x1014.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-2048x1352.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-1200x792.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_koUREOl1bI5xvA0KO-qg7Q-1980x1307.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A typical trace from Apollo’s GraphQL Tracer</figcaption></figure>



<p class="wp-block-paragraph">Our GraphQL tracer tool is still in closed beta, but I wanted to show off this screenshot anyway, because I think it’s pretty awesome. It tells you immediately how the request’s latency is broken down into the duration of different resolvers, it shows which resolvers ran concurrently and which ones had to wait for others to finish. Armed with this information, you can now make an informed decision about which part of your server needs to be optimized, and whether your optimizations actually make a difference. Pretty cool, right!?</p>



<p class="wp-block-paragraph">If you’re using GraphQL in production and would like to try out Apollo GraphQL Tracer, just drop us a line on the&nbsp;<a href="http://slack.apollostack.com/" target="_blank" rel="noreferrer noopener">Apollo Slack</a>, and we’ll work something out!</p>



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



<p class="wp-block-paragraph">That’s all I have for now. I hope that after having read this post you’ll be able to avoid some of the most common obstacles people run into when building GraphQL servers.</p>



<p class="wp-block-paragraph">There’s a lot more to write about building GraphQL servers, so if you have a question that you’d like to see answered, let me know in the comments!</p>


Backend

Remove Application Logic from Kubernetes Config

Modernize your MERN Stack with GraphQL and GraphOS

From Monolith to Federation

Designing the GraphQL schema for Propel, an analytics API platform

How Priceline.com manages PCI compliance with GraphQL

Schema-First vs Code-Only GraphQL

Where Does GraphQL Fit In the Stack? – Modern App Development with GraphQL

Past posts

Introducing Open Telemetry for Apollo Federation

The Evolution of GraphQL at Scale

Schema Services: Transitioning Towards a Federated Architecture

How to structure GraphQL server code

Backend

Remove Application Logic from Kubernetes Config

Modernize your MERN Stack with GraphQL and GraphOS

From Monolith to Federation

Designing the GraphQL schema for Propel, an analytics API platform

How Priceline.com manages PCI compliance with GraphQL

Schema-First vs Code-Only GraphQL

Where Does GraphQL Fit In the Stack? – Modern App Development with GraphQL

Past posts

Introducing Open Telemetry for Apollo Federation

The Evolution of GraphQL at Scale

Schema Services: Transitioning Towards a Federated Architecture

How to structure GraphQL server code

Stay in our orbit