Enhance customer experiences with Apollo GraphOS


<p>Writing resolvers for REST APIs has been a rite of passage for developers working with GraphQL, but what if there were an easier way? Meet Apollo Connectors.&nbsp;&nbsp;</p>



<p>As shown in Figure 1, Apollo Connectors mitigate the need to write code that connects to and returns data from REST APIs, reducing code surface area and time so you can focus on the business problem you&#8217;re trying to solve.</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdJZU6oZN7MiGs9r1tQQXZkwJJpcuPFikCrKor3lk6x3MroNldHwChst6pbHyV0h2d8fx0bdhmW7xxntWRZCNWhxOe3ZrMe-lt0P1_MZQ16jxNuOmPkQdayuZT_XW9cF_69YpmiEA?key=Tfq51hg4_0CBkUiIKxkXplEo" alt=""/></figure>



<p><em>Figure 1: Data flow showing Apollo Connector for REST APIs</em></p>



<p>In this article, we will walk through a React client web application that leverages the Apollo GraphQL client to call a public <a href="https://currencyapi.com/">CurrencyAPI</a> web service using the REST API Apollo Connector for REST APIs.&nbsp; A screenshot of the UI is seen in the following figure:&nbsp;&nbsp;</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdmYwlhbO07vkGGfTIugVC2usLpczle-KJMiJoGsGgE53FYx4zzzo3TFsFiMJ5InCSTzJ7HA7cSxtF9HRXJLQ7j6zhZ1jatfDn1WGDFQ2sY-ixRi7Fmpz-HNH2TQPQiOOmat7an?key=Tfq51hg4_0CBkUiIKxkXplEo" alt=""/></figure>



<p><em>Figure 2: Screenshot of the Currency Converter</em></p>



<p>Under the covers, the React app uses the GraphQL Client as usual and issues the query statement.&nbsp; There are no changes there.&nbsp; On the backend, you simply define the GraphQL schema file and that’s it. There is no need to create resolvers to fetch the data from the REST API.&nbsp; In the following sections, you will learn how to set up and configure the Apollo Connector for REST APIs.</p>



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



<p>In this article we will use a third party service called CurrencyAPI to fetch real-time currency exchange rates.&nbsp; At the time of this writing (Nov 2024), CurrencyAPI offers a free API key.&nbsp; If you wish to follow along, create an API key from <a href="https://currencyapi.com/">https://currencyapi.com/</a> and copy it down, as you will need it later.</p>



<p>You will also need an Apollo account and the latest version of Apollo Rover CLI.&nbsp; See sections 1 and 2 of the following Apollo Connector tutorial for installation instructions:</p>



<p><a href="https://www.apollographql.com/tutorials/connectors-intro-rest/02-setup">https://www.apollographql.com/tutorials/connectors-intro-rest/02-setup</a></p>



<p>Next, clone the repository.</p>



<p><code>git clone https://github.com/RWaltersMA/CurrencyConverter.git</code></p>



<h2 class="wp-block-heading"><a href="#obtain-api-keys-and-configure-demo" aria-hidden="true" class="aal_anchor" id="obtain-api-keys-and-configure-demo"><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>Obtain API keys and configure demo</h2>



<p>At the time of this writing, Apollo Connectors is in preview with an anticipated general availability in early 2025.&nbsp; This blog will be updated as this feature evolves.</p>



<p>Now, we are ready to configure Apollo Studio and obtain our API Key.&nbsp; Navigate to <a href="http://studio.apollographql.com/?_gl=1*tm0r8z*_gcl_aw*R0NMLjE3MzE3MDM4ODQuQ2owS0NRaUFfOXU1QmhDVUFSSXNBQmJNU1BzRm5OM1NIXzRWQWN2VHJGRFBrQkctcVltVk9ncU1iLUJjczh4YkpBOVlUZzFGQ3MyWngwZ2FBaHBfRUFMd193Y0I.*_gcl_au*MTM2NzI4NDM4Ny4xNzMwMjIwNjQ0">Apollo Studio</a> and click “Create a new Graph.”&nbsp; In the “Publish your schema using Federation” dialog, you will see toward the bottom the API Key to be used with Rover.</p>



<p>Below is a sample:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session">APOLLO_KEY=service:Currency-02wxjh:xxxxxxxxxxxxxxx \
  rover subgraph publish Currency-02wxjh@current \
  --schema ./products-schema.graphql \
  --name your-subgraph-name \
  --routing-url http://products.prod.svc.cluster.local:4001/graphql</code></pre>



<p>Copy the value for <code>APOLLO_KEY</code>.&nbsp; Open the <code>rover-dev.md file</code> and update the section with your personalized <code>APOLLO_KEY</code>.&nbsp; Copy the service name to <code>APOLLO_GRAPH_REF</code> and save the file.</p>



<p>Next, update the <code>router-config.yaml</code> file and replace the placeholders “&lt;&lt;REPLACE&gt;&gt;” with the API Key you obtained from currencyAPI and save this file.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml">preview_connectors:
  subgraphs:
    currency:
      $config:
        # Replace this value with your currencyAPI key
        apikey: &lt;&lt;REPLACE&gt;&gt;</code></pre>



<p>Now, we are ready to start a local Apollo instance.&nbsp; Copy and paste into a terminal the <code>rover dev</code> statement that is within your <code>rover-dev.md </code>file.&nbsp; For example, the command for <code>sh</code> looks like the following:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session">APOLLO_KEY=&quot;service:Currency-02wxjh:xxxxxxxxxx&quot; \
APOLLO_GRAPH_REF=&quot;Currency-02wxjh@current&quot; \
APOLLO_ROVER_DEV_ROUTER_VERSION=2.0.0-preview.1 \
rover dev --supergraph-config supergraph.yaml --router-config router-config.yaml</code></pre>



<p>If successful, the console will display the following:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">supergraph config loaded successfully
warning: Do not run this command in production! It is intended for local development only.
==&gt; Watching /Users/robwalters/Code/CurrencyConverter/currency.graphql for changes
WARN: Connector debugging is enabled, this may expose sensitive information.
==&gt; your supergraph is running! head to http://localhost:4000 to query your supergraph
successfully composed with version =2.10.0-preview.0
successfully composed with version =2.10.0-preview.0 after updating the &#039;currency&#039; subgraph</code></pre>



<div class="wp-block-group"><div class="wp-block-group__inner-container is-layout-constrained wp-block-group-is-layout-constrained">
<p>A note about <code>router-config.yaml</code>:&nbsp; In this example, we are launching a react client on the same machine as Rover.&nbsp; Since these are operating on different ports, the client on localhost:4000 and Rover on localhost:3000, the server needs to address CORS (Cross origin resource sharing).&nbsp; To do this, we added the following configuration to the <code>router-config.yaml </code>file:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml">cors:
  allow_any_origin: true</code></pre>
</div></div>



<p>Note that setting CORS to allow any origin option is not recommended for production use unless necessary.&nbsp; For more information on configuration parameters in the router, check out the <a href="https://www.apollographql.com/docs/graphos/reference/router/configuration#yaml-config-file">online documentation</a>.</p>



<h1 class="wp-block-heading"><a href="#starting-the-client" aria-hidden="true" class="aal_anchor" id="starting-the-client"><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>Starting the client</h1>



<p>Navigate to the <strong>client</strong> folder and issue:</p>



<p><code>npm install</code></p>



<p>Then</p>



<p><code>npm start</code></p>



<p>Once launched, a web browser will open to localhost:3000 and display the UI shown in Figure 2.</p>



<p>Enter any value into the amount and select your favorite base and desired currency.&nbsp; Press Convert to see the most current amount in your desired currency.</p>



<p>Let’s take a look at what is happening under the covers.&nbsp; First let’s look at the client code, specifically the <code>convert.js</code> file within the <strong>src/components </strong>folder.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GraphQL query to fetch currencyList and listExchangeRate
const GET_currencyList = gql`
  query Query {
    currencyList {
      symbol
      name
    }
    listExchangeRate {
      symbol
      rate
    }
  }
`;</code></pre>



<p>Our simple example has two queries <code>currencyList</code><strong>,</strong> which returns the complete list of symbols and names for the currency, and <code>listExchangeRate</code><strong>,</strong> which returns the current rate for each symbol.&nbsp; These data are used to populate the drop-downs in the UI.&nbsp; When using Apollo Connectors, the client does not need to make any changes.&nbsp; It is business as usual for your front-end folks.&nbsp; The real magic is in the back end.</p>



<h1 class="wp-block-heading"><a href="#taking-a-closer-look-at-the-apollo-connector" aria-hidden="true" class="aal_anchor" id="taking-a-closer-look-at-the-apollo-connector"><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>Taking a closer look at the Apollo Connector</h1>



<p>Open the <code>currency.graphql</code> file.&nbsp; This file contains the configuration for the REST Apollo Connector.&nbsp;&nbsp;</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">extend schema
  @link(
    url: &quot;https://specs.apollo.dev/federation/v2.10&quot;
    import: [&quot;@key&quot;]
  )
  @link(
    url: &quot;https://specs.apollo.dev/connect/v0.1&quot;
    import: [&quot;@source&quot;, &quot;@connect&quot;]
  )
  @source(
    name: &quot;v1&quot;
    http: {
      baseURL: &quot;https://api.currencyapi.com/v3/&quot;
      headers: [{ name: &quot;apikey&quot;, value: &quot;{$config.apikey}&quot; }]
    }
  )

type Query {
  &quot;A list of currencies&quot;
  currencyList: [Currency]
    @connect(
      source: &quot;v1&quot;
      http: { GET: &quot;/currencies&quot; }
      selection: &quot;&quot;&quot;
        data-&gt;entries {
          symbol: key
          name: value.name
        }
      &quot;&quot;&quot;
    )

  &quot;List exchange rates&quot;
  listExchangeRate: [ExchangeRate]
    @connect(
      source: &quot;v1&quot;
      http: { GET: &quot;/latest&quot; }
      selection: &quot;&quot;&quot;
        data-&gt;entries {
          symbol: key
          rate: value.value
        }
      &quot;&quot;&quot;
    )
}

type Currency {
   symbol: String
   name: String
}

type ExchangeRate {
   symbol: String
   rate: Float
}</code></pre>



<p>This is all that is needed for your Apollo Server to connect to a REST API, no extra resolver code!&nbsp; Looking at the GraphQL query, you’ll see an <code>@link</code> statement referencing Apollo Connector.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">@link(
  url: &quot;https://specs.apollo.dev/connect/v0.1&quot;
  import: [&quot;@source&quot;, &quot;@connect&quot;]
)</code></pre>



<p>Here, we are importing the <code>@source</code> and <code>@connect</code> directives.&nbsp; The <code>@connect</code> requires additional configuration parameters such as the details about the HTTP request, any headers, and a parameter called “selection” which filters the data from the REST API results.&nbsp; Here is the <code>currencyList</code> field in our example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">  &quot;A list of currencies&quot;
  currencyList: [Currency]
    @connect(
      source: &quot;v1&quot;
      http: { GET: &quot;/currencies&quot; }
      selection: &quot;&quot;&quot;
        data-&gt;entries {
          symbol: key
          name: value.name
        }
      &quot;&quot;&quot;
    )</code></pre>



<p>In this query, the Apollo Connector will use the base url defined in the <code>@link</code> and append the string defined as part of the HTTP request type in this case is GET.&nbsp; Since our currencyAPI endpoint requires an authentication header, we add the <strong>headers</strong> field and add a key-value pair referencing the API Key and value we defined earlier in the <code>router-config.yaml </code>file.&nbsp; Next, we need to tell the connector what data to extract from the API results.&nbsp; We define this in the <strong>selection</strong> parameter.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-perl">data-&gt;entries {
  symbol: key
  name: value.name
}</code></pre>



<p>For reference, the data that returns from the CurrencyAPI is similar to the following:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;data&quot;: {
    &quot;AED&quot;: {
      &quot;symbol&quot;: &quot;AED&quot;,
      &quot;name&quot;: &quot;United Arab Emirates Dirham&quot;,
      &quot;symbol_native&quot;: &quot;د.إ&quot;,
      &quot;decimal_digits&quot;: 2,
      &quot;rounding&quot;: 0,
      &quot;code&quot;: &quot;AED&quot;,
      &quot;name_plural&quot;: &quot;UAE dirhams&quot;,
      &quot;type&quot;: &quot;fiat&quot;,
      &quot;countries&quot;: [
        &quot;AE&quot;
      ]
    },
    ...
  }
}</code></pre>



<p>For our client we want to return just the symbol and name of each of the currencies.&nbsp; Since our return result has all our data under the “data” field, we start with data and iterate through each subdocument using the <strong>entities</strong> keyword.&nbsp; For each of these <strong>entities,</strong> we return the key, which in this example result is “AED” and add that value to a “symbol” field.&nbsp; We give the field “name” the value of the name field in the result. For a complete discussion and more examples of selection parameters, see the <a href="https://www.apollographql.com/docs/graphos/schema-design/connectors/selection">online documentation</a>.</p>



<h1 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</h1>



<p>Building resolvers for REST APIs can be a complex yet essential task for developers working with GraphQL. However, Apollo Connectors now provide a simpler, more efficient way to integrate REST APIs into your GraphQL schema, eliminating the need for custom resolver code. In this article, you learned how to setup and configure an Apollo Connector for REST APIs that query data from the CurencyAPI public API endpoint.&nbsp; Apollo Connectors is currently in preview, for more information, check out the <a href="https://www.apollographql.com/graphos/apollo-connectors">Apollo Connectors</a> website.</p>



<h1 class="wp-block-heading"><a href="#call-to-action" aria-hidden="true" class="aal_anchor" id="call-to-action"><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>Call to action</h1>



<p>Curious how Apollo Connectors can streamline your GraphQL workflows? Sign up for a <a href="https://www.apollographql.com/connectors-demo">demo</a> or join our upcoming webinar on December 12th, 2024: <a href="https://www.apollographql.com/events/api-orchestration-in-30-minutes-a-stripe-checkout-workflow-with-apollo-connectors">API Orchestration in 30 Minutes: A Stripe Checkout Workflow with Apollo Connectors</a>.&nbsp; After attending this webinar, you will have a solid understanding of orchestrating API calls with Apollo Connectors in the context of real-world use cases.&nbsp; If you are reading this after the event date, the webinar will be available on-demand.</p>


Effortless Data Fetching: Introducing Apollo Connectors for REST APIs


<p>GraphQL, the <em>lingua franca</em> of APIs, offers a palette of expressive tools: interfaces, nullability, deprecation, unions, etc.</p>



<p>Occasionally though, a backend’s contract would be reflected more precisely, if only it could be represented in the schema. Take unions for example: they can be used for output types, but not input types, so a search API accepting different kinds of criteria can be implemented like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  searchByName(name: String!): User
  searchById(id: ID!): User
  searchBy...
}</code></pre>



<p>This works, but is a bit tedious, and what we <em>really</em> mean is something like <code>search(name: String! | id: ID! | …)</code>. What can we do to improve the situation?<br>GraphQL is an open standard, with a working group and <a href="https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md">processes</a> in place to support its evolution: the RFCs (requests for comments).</p>



<h2 class="wp-block-heading"><a href="#the-oneof-rfc" aria-hidden="true" class="aal_anchor" id="the-oneof-rfc"><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 OneOf RFC</h2>



<p>Seeing this possible room for improvement, the GraphQL community came up with <a href="https://github.com/graphql/graphql-spec/pull/825">this RFC</a>, which proposes a new built-in directive: <code>@oneOf</code>. It can be applied to input types to indicate that one and only <strong>one of</strong> the fields must be provided.</p>



<p>In our example above, we can take advantage of it like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  search(criteria: SearchCriteria!): User
}

input SearchCriteria @oneOf {
  name: String
  id: ID
  #...
}
</code></pre>



<p>With that, a client can query <code>search({ name: “John” })</code> or <code>search({ id: “42” })</code> but <code>search({ name: “John”, id: “42” })</code> would result in a validation error.<br></p>



<p><strong>Backwards compatibility</strong></p>



<p>A nice property of the proposal is that it doesn’t introduce any new syntax and therefore should be transparent for any client libraries that have no knowledge of the new directive.</p>



<p>If you provide more than one field to a OneOf input type, a “OneOf aware” library will warn you early, before executing the operation. An older library will treat the input type as a regular one, and will allow its execution, but the <strong>backend</strong> will then provide an error, as expected.<br>To achieve this compatibility, all the fields of a OneOf input type must be declared as if they were <strong>nullable</strong> (without an exclamation mark).</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">input SearchCriteria @oneOf {
  name: String
  id: ID! # Illegal!
  type: Type! # Illegal!
}</code></pre>



<p>Without that requirement, pre-OneOf client libraries would require to provide <strong>all</strong> non-nullable fields &#8211; which wouldn’t make sense since only <strong>one</strong> field must be provided.</p>



<p>Note: although the fields are declared in the schema as nullable, passing the value null is not allowed. This may seem counterintuitive at first but the reason lies within GraphQL’s type system &#8211; <a href="https://github.com/graphql/graphql-spec/pull/825#issuecomment-1835978233">this RFC comment</a> explains it all.</p>



<h2 class="wp-block-heading"><a href="#support-in-apollo-kotlin" aria-hidden="true" class="aal_anchor" id="support-in-apollo-kotlin"><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>Support in Apollo Kotlin</h2>



<p>If you are an Apollo Kotlin user and want to try @oneOf today, you’re in luck! We’ve added experimental support for it in <a href="https://www.apollographql.com/blog/apollo-kotlin-4-is-now-available">version 4</a>:</p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes#downloading-a-schema">Fetching a schema</a> via introspection on a OneOf-aware server will include the <code>@oneOf</code> directives.</li>
</ul>



<ul class="wp-block-list">
<li>You’ll get a runtime error if you build a oneOf input type and provide more than one field:</li>
</ul>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">SearchCriteria.Builder()
  .name(&quot;Luke&quot;)
  .id(&quot;42&quot;)
  .build() // Throws! Must provide only one field.</code></pre>



<ul class="wp-block-list">
<li>When using&nbsp;<a href="https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin/">the IDE plugin</a> you’ll get errors in the editor:</li>
</ul>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="926" height="232" src="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01.png" alt="In Kotlin" class="wp-image-23879" srcset="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01.png 926w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01-300x75.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01-768x192.png 768w" sizes="auto, (max-width: 926px) 100vw, 926px" /></figure>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="180" src="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-1024x180.png" alt="In GraphQL" class="wp-image-23881" srcset="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-1024x180.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-300x53.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-768x135.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-1200x211.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59.png 1322w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>With <a href="https://github.com/apollographql/apollo-server" data-type="link" data-id="https://github.com/apollographql/apollo-server">Apollo Server</a>, you can use <code>@oneOf</code> in your schemas starting from version 4.</p>



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



<p>The GraphQL RFC process is an iterative one. The OneOf RFC is currently in Stage 2 (“Draft”), which <a href="https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md#stage-2-draft">means</a> it is thought to be ready to be accepted into the specification but awaiting feedback from the community. Try it today with Apollo Kotlin and Apollo Server, and make your voice heard on <a href="https://github.com/graphql/graphql-spec/pull/825">the ticket</a> and in the Apollo <a href="https://github.com/apollographql/apollo-kotlin/issues">issue</a> <a href="https://github.com/apollographql/apollo-server/issues">trackers</a>.</p>


More expressive schemas with @oneOf

Federated Subscriptions with HTTP Callback Protocol

Federated Subscriptions with Router’s HTTP Callback Protocol


<h3 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</h3>



<p>GraphQL streamlines data flow between clients and services, acting as the composition layer in the middle. As businesses strive for scalable and maintainable solutions as their services grow, a federated GraphQL API is becoming the go-to architecture to meet these evolving demands.&nbsp;</p>



<p>If you&#8217;re searching for helpful beginner resources to dive into GraphQL and Apollo Federation, we&#8217;ve got you. <a href="https://www.apollographql.com/tutorials/">Odyssey</a> is Apollo&#8217;s official learning platform, where you can boost your developer skills with hands-on GraphQL tutorials and trainings.</p>



<p>Over the past year, Apollo’s Education team has helped close to 40,000 learners on their GraphQL learning journey, starting with JavaScript and Apollo Server implementations.&nbsp;</p>



<p>Because GraphQL&#8217;s potential stretches far beyond the JavaScript realm, we&#8217;ve expanded our curriculum to support three new languages: Java, .NET (C#) and TypeScript.</p>



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



<h4 class="wp-block-heading"><a href="#getting-to-know-graphql" aria-hidden="true" class="aal_anchor" id="getting-to-know-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>Getting to know GraphQL</h4>



<p>In the first course, &#8220;Intro to GraphQL&#8221;, you&#8217;ll build the core of a music catalog API: showcasing featured playlists, listing a playlist&#8217;s tracks, and adding tracks. Along the way, you&#8217;ll learn how to:</p>



<ul class="wp-block-list">
<li>Implement a GraphQL server</li>



<li>Use an existing REST API as a data source</li>



<li>Describe the journey of a GraphQL operation from client to server and back</li>



<li>Follow best practices for writing and designing queries and mutations</li>
</ul>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="728" src="https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-1024x728.png" alt="" class="wp-image-23476" srcset="https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-1024x728.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-300x213.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-768x546.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-1536x1093.png 1536w, https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-2048x1457.png 2048w, https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-1200x854.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/03/graphql-server-request-response-1980x1409.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>In the second course, you&#8217;ll learn about federation and add a new domain to your GraphQL API. You&#8217;ll learn how to:</p>



<ul class="wp-block-list">
<li>Describe the architecture of a supergraph (subgraphs and the router)</li>



<li>Create entities in a federated schema</li>



<li>Explore graph insights and schema delivery</li>



<li>Ship features safely using the Rover CLI&#8217;s features to publish subgraphs, run schema checks and facilitate local development</li>
</ul>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="604" src="https://wp.apollographql.com/wp-content/uploads/2024/03/router-subgraphs-1-1024x604.png" alt="" class="wp-image-23480" srcset="https://wp.apollographql.com/wp-content/uploads/2024/03/router-subgraphs-1-1024x604.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/03/router-subgraphs-1-300x177.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/03/router-subgraphs-1-768x453.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/03/router-subgraphs-1-1200x708.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/03/router-subgraphs-1.png 1440w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>These courses are currently offered in three different flavors, depending on which language you&#8217;re most comfortable with. Each language uses a specific framework or library:</p>



<ul class="wp-block-list">
<li>.NET (C#) &amp; Hot Chocolate</li>



<li>Java &amp; DGS</li>



<li>TypeScript &amp; Apollo Server</li>
</ul>



<p>&gt; Coming soon: Python &amp; Strawberry! Let us know if you want to see other languages or frameworks.</p>



<h3 class="wp-block-heading"><a href="#testing-your-understanding" aria-hidden="true" class="aal_anchor" id="testing-your-understanding"><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>Testing your understanding</h3>



<p>Each lesson ends with a <strong><em>Practice</em></strong> section to assess your knowledge and understanding. By answering the multiple choice questions or fill-in-the-blank quizzes, you&#8217;ll reinforce the concepts you&#8217;ve learned about. Don&#8217;t worry, you&#8217;ve got three tries to get it right, and the course contents have the answers!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="2403" height="1502" src="https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited.png" alt="" class="wp-image-23474" srcset="https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited.png 2403w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-300x188.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-1024x640.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-768x480.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-1536x960.png 1536w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-2048x1280.png 2048w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-1200x750.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/03/practice-example-edited-1980x1238.png 1980w" sizes="auto, (max-width: 2403px) 100vw, 2403px" /></figure>



<p>Completing each <strong><em>Practice</em></strong> section brings you one step closer to overall course completion status!</p>



<h3 class="wp-block-heading"><a href="#asking-for-help" aria-hidden="true" class="aal_anchor" id="asking-for-help"><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>Asking for help</h3>



<p>We all get stuck sometimes; it&#8217;s part of the process! You&#8217;ve got a few different ways to reach out:</p>



<ul class="wp-block-list">
<li><strong><em>In-lesson comments</em></strong><em>:</em> At the bottom of each lesson, you&#8217;ll find a space to share your thoughts, questions or issues. You can read other learners&#8217; comments and contribute answers too.</li>



<li><a href="https://discord.gg/graphos"><strong><em>Discord</em></strong></a><em>:</em> Find thousands of other GraphQL developers, including Apollo engineers, to discuss topics and share experiences.</li>



<li><a href="https://community.apollographql.com/"><strong><em>Community forum</em></strong></a><em>:</em> Don&#8217;t forget to tag your post with <code>odyssey</code>!</li>
</ul>



<p>You can use these channels to share your feedback too! These courses are currently still in beta, and we&#8217;ll continue to iterate based on your experiences.</p>



<h3 class="wp-block-heading"><a href="#next-steps" aria-hidden="true" class="aal_anchor" id="next-steps"><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>Next steps</h3>



<p>Ready to learn? Find your language of choice and get started:</p>



<p><strong>For those new to GraphQL, try </strong><strong><em>Intro to GraphQL with…</em></strong></p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/tutorials/intro-hotchocolate">.NET (C#) and Hot Chocolate</a></li>



<li><a href="https://www.apollographql.com/tutorials/intro-dgs">Java and DGS</a></li>



<li><a href="https://www.apollographql.com/tutorials/intro-typescript">TypeScript and Apollo Server</a></li>
</ul>



<p><strong>For those already familiar with GraphQL, try </strong><strong><em>Federation with…</em></strong></p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/tutorials/federation-hotchocolate">.NET (C#) and Hot Chocolate</a></li>



<li><a href="https://www.apollographql.com/tutorials/federation-dgs">Java and DGS</a></li>



<li><a href="https://www.apollographql.com/tutorials/federation-typescript">TypeScript and Apollo Server</a></li>
</ul>



<p>Looking forward to reading your feedback!</p>


Learn GraphQL & Federation with .NET, Java, or TypeScript


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


Remove Application Logic from Kubernetes Config


<p>Most articles explaining the benefits of GraphQL focus on advantages for the frontend: things like preventing overfetching, reducing round trips, and iterating faster. But GraphQL provides just as many advantages for backend developers, which is why I choose it by default for new APIs and why you should consider it, too.</p>



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



<p>The goal of building any API is to <a href="https://www.postman.com/state-of-api/api-first-strategies/#measuring-success-of-public-apis">enable someone to use it</a>, which requires excellent communication between API producers and consumers. However, the state of the art for REST APIs doesn’t quite live up to this expectation.</p>



<p>On the backend, developers either need to manually document the entire API or rely on auto-generation tools that don’t fully meet their needs. Consumers face the same choice, write code by hand or workaround the bugs in their SDK generator (stated, lovingly, as the maintainer of <a href="https://github.com/openapi-generators/openapi-python-client">an OpenAPI client generator</a>). On top of this, these solutions result in inconsistent understandings of the API. Reproducing errors becomes time-consuming and frustrating, which feels like a battle instead of a collaboration. What we need is a shared language to describe how the API works—one that doesn’t add unnecessary layers of abstraction or manual work.</p>



<p>Meet GraphQL, where every team uses the same schema definition language (SDL) to talk about the API. SDL is designed for developers, omitting extraneous details while describing all the essential bits. This serves both as your documentation and a universal language to communicate between teams.</p>



<p>On the backend, developers can write code in their language of choice and have the SDL created for them. Alternatively, they can write the SDL by hand, and generate the required code. Either way, the documentation is always kept in sync with the implementation.</p>



<p>Consumers use this same SDL directly, so there’s no need to maintain a separate documentation website. Instead, they can get information, auto-complete names, and see potential mistakes right in their IDEs. The same request they write in their code can be run by itself for easier debugging, which makes sending snippets to the backend team much more straightforward. With clearer communication, there will be fewer open issues and less wasted time tracking down minor bugs.</p>



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



<p>Bikeshedding is when you spend time discussing decisions that don’t have a significant impact, and it happens quite a bit with RESTful APIs. To name a few, <em>I</em> have been in bikeshedding meetings about:</p>



<ol class="wp-block-list">
<li>Which verb to use? <code>PUT</code> and <code>POST</code> could have a lot of overlap. Maybe you <em>should</em> use <code>GET</code>, but the fact that it can’t contain a body is too limiting for the amount of filters you need.</li>



<li>Should this be a query parameter, path parameter, form data, or JSON body? For path parameters, how should we serialize arrays? What about objects?</li>



<li>Do we completely normalize endpoints to reduce duplication, even though that causes slower client performance? Or include the kitchen sink even though that causes slower individual endpoint performance? Maybe a compromise with shallow nested objects containing only the most common parameters or a parameter that allows selecting fields, emulating GraphQL without the type safety.</li>



<li>Which HTTP status code is the right one for each response?</li>



<li>Should relationships be indicated with IDs or URIs?</li>
</ol>



<p>Hopefully, these discussions will lead to a comprehensive style guide, but the meetings will continue even with those guides. While there will always be <em>some</em> debate around things like naming, GraphQL eliminates entire categories of potential style issues (including all those above) by being <em>simpler</em>. You can spend less time on the little details and more time solving more interesting problems.</p>



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



<p>Imagine you have a <code>/v1/data</code> endpoint called by all your frontend teams: web, iOS, and Android. You decide that the date field should return UTC instead of localized time, so how do you make that breaking change? It usually looks something like this:</p>



<ol class="wp-block-list">
<li>Create a new <code>/v2/data</code> endpoint.</li>



<li>Inform all the client teams that this new endpoint exists and that they should migrate by some date.</li>



<li>Track metrics on <code>/v1/data</code> and send reminders to consumers who haven’t updated.</li>



<li>The deprecation date comes and goes, and you’re still receiving calls to the old endpoint.</li>



<li>You either pull the plug and start breaking things or, more likely, continue to support the <code>/v1/data</code> endpoint indefinitely, creating tech debt with no apparent payoff date.</li>
</ol>



<p>Now, let’s play through the same scenario with GraphQL. First, you add <code>@deprecated(reason: “use utcDate”)</code> to your old <code>date</code> field and add the new <code>utcDate</code> field. API consumers immediately start seeing warnings in their IDEs and potentially CI/CD about this deprecation since most GraphQL tooling supports it.</p>



<p>As it turns out, the iOS and Android teams weren’t even using the old <code>date</code> field, so no changes are necessary for them!</p>



<p>Someone on the web team notices some squiggly lines in their editor and decides to fix them, following the instructions left in the <code>reason</code> field. Your backend metrics tell you that the date field is no longer in use, and you’re safe to remove it!</p>



<p>Creating less churn and an easier upgrade path for clients makes them more likely to upgrade. If they upgrade faster, you can remove that stale old code faster, too!</p>



<h2 class="wp-block-heading"><a href="#graphql-is-for-you-too" aria-hidden="true" class="aal_anchor" id="graphql-is-for-you-too"><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>GraphQL is for you too</h2>



<p>One of the main features of GraphQL is its developer experience. By creating a shared language between teams, reducing complexity, and providing a smoother upgrade path, GraphQL makes building and maintaining APIs more delightful. That’s why, even if your frontend engineers aren’t pushing for it yet, you should start evaluating GraphQL for your tech stack. If you have any questions or disagree with anything I’ve said above, let me know on our <a href="http://discord.gg/NUaGwceDhX">Discord server</a>! If you want to be notified of future posts, there’s also a channel for that.</p>


GraphQL is for Backend Engineers


<p>In the ever-evolving landscape of software development, the way we access and interact with data has seen remarkable changes. One of the most significant advancements in recent years is GraphQL, a query language for APIs that has quickly gained popularity and is poised to shape the future of how we work with APIs.</p>



<p>Developers and organizations are always on the lookout for technologies that can streamline their processes and improve efficiency. GraphQL offers a powerful solution to many of the challenges that developers face when working with traditional REST APIs. In this blog post, we&#8217;ll explore why GraphQL is not just a passing trend but indeed the future for APIs.</p>



<h2 class="wp-block-heading"><a href="#enhancing-developer-portals" aria-hidden="true" class="aal_anchor" id="enhancing-developer-portals"><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>Enhancing Developer Portals</h2>



<p>Developer portals are the gateway for developers to interact with APIs. They serve as documentation hubs, offering insights into the available endpoints, data structures, and usage guidelines. GraphQL shines in this area by providing a more intuitive and developer-friendly experience.</p>



<ul class="wp-block-list">
<li><strong>Self-Documenting APIs</strong>: With GraphQL, APIs are inherently self-documenting. Developers can explore the schema, understand data types, and discover available queries and mutations right from the GraphQL endpoint. This eliminates the need for maintaining separate documentation and ensures that it stays up-to-date.</li>



<li><strong>Precise Data Fetching</strong>: GraphQL allows developers to request only the data they need, avoiding over-fetching and under-fetching of data. This precision in data fetching results in more efficient and faster applications.</li>



<li><strong>Versioning Made Easier</strong>: Traditional REST APIs often require versioning when making changes, which can lead to API fragmentation. GraphQL&#8217;s flexible schema and backward-compatible changes make versioning a thing of the past, reducing complexity and making API evolution smoother.&nbsp;</li>
</ul>



<h2 class="wp-block-heading"><a href="#platform-engineering-efforts" aria-hidden="true" class="aal_anchor" id="platform-engineering-efforts"><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>Platform Engineering Efforts</h2>



<p>Platform engineering involves building a robust foundation for an organization&#8217;s software ecosystem. The practice of platform engineering is rapidly growing. Gartner predicts that 80% of engineering organizations will establish platform engineering teams for internal usage by 2026 (<a href="https://www.gartner.com/en/articles/what-is-platform-engineering"><em>Gartner, What is Platform Engineering?</em></a>). Even with this rapid growth in the practice, the task of bringing together multiple services can be extremely complex (especially when you have 100s of APIs). GraphQL Federation is a game-changer in this regard, providing the missing composable layer for APIs.&nbsp;</p>



<ul class="wp-block-list">
<li><strong>Composable APIs</strong>: GraphQL Federation allows organizations to break down their monolithic APIs into smaller, more manageable components called services. These services can be developed, tested, and deployed independently. This modularity enhances scalability and maintenance efforts.</li>



<li><strong>Efficient Data Coordination</strong>: With Federation, the composition of data from multiple services is seamless. GraphQL handles the data stitching behind the scenes, ensuring that developers can retrieve related data across services without the need for complex, custom code.</li>



<li><strong>Centralized Governance</strong>: Federation enables centralized governance of APIs and data models. Organizations can define common types and queries, ensuring consistency across services. This centralization simplifies security, access control, and compliance efforts.</li>
</ul>



<h2 class="wp-block-heading"><a href="#scaling-api-efforts-seamlessly" aria-hidden="true" class="aal_anchor" id="scaling-api-efforts-seamlessly"><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>Scaling API Efforts Seamlessly</h2>



<p>As organizations grow, so do their API needs. GraphQL Federation empowers organizations to scale their API efforts seamlessly. Data ownership is flexible where different teams within an organization can own and manage their services independently, making it easier to scale development efforts horizontally. Developers can collaborate more efficiently by working on smaller, focused services. This reduces bottlenecks and accelerates feature delivery.</p>



<p>Not only do you get more efficient collaboration, every developer gets to take advantage of improved performance thanks to GraphQL’s efficient data retrieval. A graph router can create optimized query plans that improve application performance compared to some hand-writtten backend-for-frontend code, even as API complexity grows.</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>In conclusion, GraphQL is not just a buzzword; it&#8217;s a transformative technology that is here to stay. Its benefits in enhancing developer portals, simplifying platform engineering efforts, and enabling seamless scalability make it the future of APIs. Embracing GraphQL now can put your organization at the forefront of the API evolution, ensuring you stay agile and competitive in the ever-changing tech landscape. The future of APIs is GraphQL, and the future is now.</p>



<p><em>This article is part of APIFutures, a distributed, creator-led effort to identify the most significant opportunity and/or the greatest challenge facing the API community in 2024. You can check out other articles and viewpoints on the </em><a href="https://matthewreinbold.github.io/APIFutures/index.html"><em>APIFutures hub</em></a><em>.</em></p>


GraphQL is the Future for APIs

Office Hours: Apollo Server with Trevor Scheer


<p>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>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>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>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>express.Router</code> that serve the API endpoints for your client app:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">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>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>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="language-">//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="language-">//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>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>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>@apollo/server</code></a> and <a href="https://www.apollographql.com/docs/react/development-testing/static-typing#setting-up-your-project"><code>@apollo/client</code></a>. In my opinion, this produces part of the ideal developer experience 😍</p>



<p>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>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>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">npm install @apollo/server @apollo/subgraph graphql graphql-tag</code></pre>



<p><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>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>@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>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>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">//schema.graphql
type Query {
  record(id: ID!): Record
  records: [Record]
}

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



<p>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">//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>Lastly, we need to expose the <code>/graphql</code> route in our express app. In your server.js (or wherever you define your express app), we’ll use <code>@apollo/server</code> to expose the <code>/graphql</code> route:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">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>Now you should be able to run your server project and visit <code>/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>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">npm install @apollo/client graphql</code></pre>



<p>Next, we need to add the <code>ApolloProvider</code> to our React app:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// 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><code>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>Now we’re ready to start utilizing the hooks <code>@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>recordList.js</code> to our GraphQL route:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// 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>Now you should be able to start your client application and the records will be loaded through your GraphQL route ✨</p>



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



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



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



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



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



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



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



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



<li>Inventory</li>



<li>Cart</li>



<li>Order</li>



<li>Payment</li>



<li>Customer account</li>



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1024" height="768" src="https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed.jpg" alt="" class="wp-image-22297" srcset="https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2023/08/7.-Monolith-removed-768x576.jpg 768w" sizes="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>The end state of the transformation is achieved once all the domains in the monolith have been migrated, thus allowing the org to successfully rid themselves of the monolith.</p>



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



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



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



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


From Monolith to Federation

Designing our GraphQL Schema for Propel, an analytics platform

Designing the GraphQL schema for Propel, an analytics API platform


<p>The Apollo Router features three customization options out of the box to adjust behavior: <a href="https://www.apollographql.com/docs/router/configuration/overview">configuration options</a>, <a href="https://www.apollographql.com/docs/router/customizations/rhai">Rhai scripting</a>, and <a href="https://www.apollographql.com/docs/router/customizations/coprocessor">external coprocessing</a>. We refer to these as extensibility options.</p>



<p>Extensibility of the Router is one of its primary strengths and is a critical feature for many organizations large and small. Understanding the performance implications of these options is important as the Router is designed for performance and serves as the entry point to your supergraph. We’re excited to share results with you covering these extensibility options, as well as a public GitHub repository where you can test them yourself.&nbsp;</p>



<p>Before diving into the methodology and detailed results, the high-level results are:&nbsp;</p>



<ul class="wp-block-list">
<li>When you’re able to choose, configuration options perform better than Rhai scripts, and Rhai scripts perform better than external coprocessing.&nbsp;</li>



<li>When you must use an external coprocessor for more complex logic, we see about 350μs overhead.&nbsp;</li>



<li>The choice of programming language, complexity of task, network proximity, type of host machine, and other factors will have varying impacts on the real-world performance of your Router and coprocessor, so ensure you consider the best tool for the job, so to speak, and keep the coprocessor as close as possible to the Router. Ideally this would be within the same Pod (if using Kubernetes) or similar for other orchestration systems.&nbsp;</li>
</ul>



<p><a href="https://github.com/apollosolutions/router-extensibility-load-testing">The GitHub repository</a> includes more information about the results, including specific numbers, as well as the ability to run these tests yourself.&nbsp;</p>



<h3 class="wp-block-heading"><a href="#methodology" aria-hidden="true" class="aal_anchor" id="methodology"><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>Methodology</strong></h3>



<p>As with any test, determining how to best isolate the variable you want is critical to ensure you’re not introducing other factors into the results. For the tests we ran, we wanted to isolate the overhead for each extensibility option, not the performance impact of each test we ran.</p>



<p>To help isolate overhead latency, we ensured that we pre-warmed the query plan cache to remove the initial overhead of query planning to the first request (which may have skewed results by adding a request with a higher maximum latency value). We do this by running curl commands after the Router restart with both of the test queries.&nbsp;</p>



<p>We also limited the resources for each running Docker image to use only 1 CPU core and 1GB of RAM as a way to ensure a consistent result from run to run. While this may have impacted some programming language implementations, we wanted to give a level playing field for each test.&nbsp;</p>



<p>With that in mind, we designed three different tests for the extensibility options. This allowed us to show various overheads, as well as showing the impact of not only the complexity, but potential impact of the coprocessor stages.&nbsp;</p>



<ul class="wp-block-list">
<li>Setting a static subgraph header, which is supported by all three extensibility options. This was the simplest example available, and helped test the overhead of a SubgraphRequest coprocessor stage. Since this logic is run per-subgraph on both the coprocessor and in Rhai, we wanted to understand the overhead of multiple invocations.&nbsp;</li>



<li>Setting 10 GUID headers on a response, which is supported by only Rhai and external coprocessing. This test was designed to have slightly more complex logic, while also showing something that wasn’t possible with a basic configuration.&nbsp;</li>



<li>Lastly, we tested setting the client awareness headers using claims within a JSON Web Token (JWT) which can only be done in a coprocessor as of writing. This was the most complex logic we tested, and was a way to show how complexity could affect results as well as being an example of something only possible with external coprocessing.&nbsp;</li>
</ul>



<p>Each of these tests were run against a baseline Router (that is, a basic Router without any configured extensibility options), and a Router with the respective extensibility options configured with coprocessors being implemented in Node.js, Python, Go, Java, and C#. Between each run, we restart the Router and pre-warm the query plan cache.&nbsp;</p>



<p>For every test, we utilized<a href="https://github.com/apollosolutions/router-extensibility-load-testing/tree/main/loadtester"> a custom version</a> of<a href="https://github.com/tsenart/vegeta"> Vegeta</a>, a Go-based load testing utility. Our version handles GraphQL errors within the payload and treats them as non-2XX results for the purposes of reporting failures appropriately. Each run was set to 100 requests per second for 60 seconds to adequately load-test the system and provide enough data points for reference.&nbsp;</p>



<h3 class="wp-block-heading"><a href="#results" aria-hidden="true" class="aal_anchor" id="results"><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>Results</strong></h3>



<h4 class="wp-block-heading"><a href="#overview" aria-hidden="true" class="aal_anchor" id="overview"><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>Overview</strong></h4>



<p>Diving into the results, we saw that most workloads benefit by using configuration options over Rhai scripts, and Rhai scripts are better than external coprocessing in terms of overhead.&nbsp;</p>



<p>Rhai performance was excellent across the board, with latency overheads in p95s being around 100μs. This overhead makes it an excellent choice for most customization needs, as it tends to cover most use-cases that can’t traditionally be done with the basic configuration options.&nbsp;</p>



<p>External coprocessing overhead was still excellent at 350μs overhead per stage average across all tests and languages, so for those that need more complex logic (such as the client awareness test showed), it can still be an excellent fit with great performance. With that in mind, there are additional elements here that are worth diving into.&nbsp;</p>



<ul class="wp-block-list">
<li>Your runtime/programming language matters, and will affect results depending on the type of customizations you need.&nbsp;</li>
</ul>



<p>Each language has its strengths and weaknesses, so ensure you pick the right tool for the job when deciding what to use for your coprocessor.</p>



<ul class="wp-block-list">
<li>Even more important than runtime, your networking setup is critical to ensuring optimal performance.&nbsp;</li>
</ul>



<p>Since external coprocessing communicates over HTTP, reducing the latency between your Apollo Router and external coprocessor will ensure optimal performance and reduce overhead. If you are using Kubernetes, for example, running the coprocessor as a container alongside the Router in the same Pod can ensure network proximity.&nbsp;</p>



<ul class="wp-block-list">
<li>Ensure you need to use SubgraphRequest/Response stages before using them</li>
</ul>



<p>The coprocessor overhead is per stage, so if you run a query that hits 5 subgraphs, you’ll end up with 5 invocations of the SubgraphRequest/Response stages for a coprocessor. This overhead can add up quickly, so it is advisable to validate your need to use this stage before utilizing it.&nbsp;</p>



<h4 class="wp-block-heading"><a href="#per-test-results" aria-hidden="true" class="aal_anchor" id="per-test-results"><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>Per-Test Results</strong></h4>



<p>Looking at each test individually, we can start to make sense of some of the above information, as well as see the percentage differences from the baseline.</p>



<p>The numbers used were from the most recent test, running on Windows using WSL2, but your latency numbers may vary depending on resources available, CPU, OS, and more. The takeaways themselves should remain the same.</p>


<div class="wp-block-image is-style-default">
<figure class="aligncenter size-full"><img loading="lazy" decoding="async" width="600" height="371" src="https://wp.apollographql.com/wp-content/uploads/2023/07/Static-Subgraph-Header-Latency.png" alt="Chart showing the differences between the extensibility options." class="wp-image-21837" srcset="https://wp.apollographql.com/wp-content/uploads/2023/07/Static-Subgraph-Header-Latency.png 600w, https://wp.apollographql.com/wp-content/uploads/2023/07/Static-Subgraph-Header-Latency-300x186.png 300w" sizes="auto, (max-width: 600px) 100vw, 600px" /><figcaption class="wp-element-caption">Results for setting a static subgraph header</figcaption></figure></div>


<p>For the static subgraph header test, we added a &#8220;coprocessor&#8221; header with the value of the type of extensibility (e.g. rhai for Rhai scripts). This leveraged the SubgraphRequest stage for a coprocessor, and we aimed to test the overhead of making multiple requests. For this test, we averaged 1.5 subgraphs per request.</p>



<p>We can start to see that we are running into minute variance issues. In the above chart, we show that both Python and the config option are faster than the baseline- but the raw data shows that they are only 40μs and 10μs difference, respectively. Regardless, the actual overhead was measured around 330μs averaged across all coprocessor types. For specific details on each option, see the<a href="https://github.com/apollosolutions/router-extensibility-load-testing/tree/main#static-subgraph-header"> full results in the GitHub repository</a>.</p>


<div class="wp-block-image">
<figure class="aligncenter size-full"><img loading="lazy" decoding="async" width="600" height="371" src="https://wp.apollographql.com/wp-content/uploads/2023/07/10-GUID-Response-Headers-Latency.png" alt="" class="wp-image-21839" srcset="https://wp.apollographql.com/wp-content/uploads/2023/07/10-GUID-Response-Headers-Latency.png 600w, https://wp.apollographql.com/wp-content/uploads/2023/07/10-GUID-Response-Headers-Latency-300x186.png 300w" sizes="auto, (max-width: 600px) 100vw, 600px" /><figcaption class="wp-element-caption">Results for adding 10 GUIDs to a header in the response</figcaption></figure></div>


<p>In the GUID response headers test, we wanted to add a level of logic that the configuration couldn&#8217;t provide, as well as test the impact of a very basic looping logic to add dynamically generated GUIDs to the Router&#8217;s response. To do so, we leveraged the RouterResponse stage for a coprocessor.</p>



<p>Breaking down the numbers, we see clearly that Rhai is far more performant- only 11% higher p95 latency than baseline, or only 10μs in our tests versus the minimum 17% change when using a Go-based coprocessor, and the others being higher.</p>


<div class="wp-block-image">
<figure class="aligncenter size-full"><img loading="lazy" decoding="async" width="600" height="371" src="https://wp.apollographql.com/wp-content/uploads/2023/07/Client-Awareness-Headers-from-JWT-Latency.png" alt="" class="wp-image-21835" srcset="https://wp.apollographql.com/wp-content/uploads/2023/07/Client-Awareness-Headers-from-JWT-Latency.png 600w, https://wp.apollographql.com/wp-content/uploads/2023/07/Client-Awareness-Headers-from-JWT-Latency-300x186.png 300w" sizes="auto, (max-width: 600px) 100vw, 600px" /><figcaption class="wp-element-caption">Results for identifying clients based on JWT claims</figcaption></figure></div>


<p>For our last test, we wanted to test something logically complex as well as something only a coprocessor could do. This test decoded a JWT using an HMAC256 secret, and then used the claims to populate the apollographql-client-name and apollographql-client-version headers<a href="https://www.apollographql.com/docs/router/managed-federation/client-awareness/"> to enable client awareness</a> for visibility in Apollo Studio.</p>



<p>This test shows how, while the HTTP overhead itself is minimal, the actual logic is far more important. Introducing complex logic can affect performance in a meaningful way, so using other extensibility options whenever possible will help reduce the overall overhead.</p>



<h3 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></h3>



<ol class="wp-block-list">
<li>Prefer Router configuration options over other customization options whenever possible.</li>



<li>External coprocessors add, on average, only 350μs of overhead plus the overhead of your logic. This number can change depending on other factors, identified above.</li>



<li>Keep coprocessors as close as possible to the Router to ensure the overhead doesn&#8217;t become too burdensome.</li>
</ol>



<p>View the full results and implementation on the<a href="https://github.com/apollosolutions/router-extensibility-load-testing"> public GitHub page</a>.</p>


Text that reads "Performance impacts of Apollo Router customizations" with an astronaut to the right of the text.

Performance impacts of Apollo Router customizations

Add Rust to your GraphQL API with GraphOS

Add Python to your GraphQL API with GraphOS and Strawberry GraphQL


<p>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>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"># schema.graphql using schema-first
type Query {
  hello: String
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// 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>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">// 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>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>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>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>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>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>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>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>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">// 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>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>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>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">// 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>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

Building a GraphQL server in Go with go-graphql

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

Federated Schema Design


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


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

Introduction to Apollo Federation


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



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



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



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



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



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



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



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



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



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



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



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


Introducing the Apollo Federation Best Practices Series


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


Apollo Federation 2 and Gateway 2.0 are now available in preview


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



<p>Consider this operation:</p>



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



<p></p>


Faster federated graphs and better usage data with Apollo Server 3.6


<p>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>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>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>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>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>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>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>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>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>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>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>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>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>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

Using GraphQL with Golang


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



<p>Happy coding!</p>


Apollo Workbench: A Better Way to Design Federated Graphs


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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

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

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

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

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



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



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



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



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



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



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



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

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



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



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



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



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

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



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



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



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



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



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


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



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



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



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



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



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



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



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


Federation in Odyssey

Using GraphQL with Python – A Complete Guide

Why You Should Disable GraphQL Introspection In Production – GraphQL Security


<p>GraphQL lets front-end developers simplify their data-fetching and state management approaches. For backend developers, GraphQL acts as a structured, maintainable API. To learn how GraphQL works across the stack, I recommend completing a fullstack GraphQL tutorial.</p>



<p>In this short post, I&#8217;d like to share two GraphQL training resources that we created @ Apollo to help you ramp up and get comfortable building GraphQL applications from back to front.</p>



<h2 class="wp-block-heading"><a href="#%f0%9f%93%bd%ef%b8%8f-watch-learn-graphql-the-lift-off-series-on-odyssey-the-apollo-course-platform" aria-hidden="true" class="aal_anchor" id="%f0%9f%93%bd%ef%b8%8f-watch-learn-graphql-the-lift-off-series-on-odyssey-the-apollo-course-platform"><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>📽️ [Watch] Learn GraphQL &#8211; The lift-off series on Odyssey: the Apollo Course Platform</h2>



<p>Earlier this year, we released <a href="http://odyssey.apollographql.com/?referrer=blog">Odyssey: the Apollo course platform</a>. We wanted to create a more directed, interactive, and fun learning experience for developers in search of practical training using GraphQL and Apollo.</p>



<p>The first series of courses on Odyssey is called <strong>Lift-off</strong>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="960" height="645" src="https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-1.png" alt="" class="wp-image-6871" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-1.png 960w, https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-1-300x202.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-1-768x516.png 768w" sizes="auto, (max-width: 960px) 100vw, 960px" /></figure>



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



<p>In <em>Lift-off,</em> you&#8217;ll build a full-stack GraphQL example application called Catstronauts, a learning platform for adventurous cats who want to explore the universe!</p>



<p>It contains list-view and detail-view pages of all the different courses.</p>



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



<p>In <em>Lift-off part I</em>, you&#8217;ll learn the core components of a full-stack GraphQL app, specifically:</p>



<ul class="wp-block-list">
<li>a schema first-approach to building web applications with GraphQL</li>



<li>GraphQL&#8217;s Schema Definition Language (SDL)</li>



<li>how to set up Apollo Server, test, and develop it using <a href="https://studio.apollographql.com/dev?referrer=blog">Apollo Explorer</a></li>



<li>how to connect to your GraphQL API from the front-end using Apollo Client and React</li>
</ul>



<p>And in the second part of the series, you&#8217;ll learn:</p>



<ul class="wp-block-list">
<li>how to write more advanced queries and display data in the UI</li>



<li>how to use variables</li>



<li>how to mutate data and update the UI</li>
</ul>



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



<p>Ready to start? Head on over to <a href="https://odyssey.apollographql.com/?referrer=blog">odyssey.apollographql.com</a>.</p>



<h2 class="wp-block-heading"><a href="#%f0%9f%93%96-read-learn-graphql-the-official-apollo-full-stack-graphql-tutorial" aria-hidden="true" class="aal_anchor" id="%f0%9f%93%96-read-learn-graphql-the-official-apollo-full-stack-graphql-tutorial"><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>📖 [Read] Learn GraphQL &#8211; The Official Apollo Full-stack GraphQL Tutorial</h2>



<p>For those that prefer the written approach to learning, I recommend checking out the <a href="https://www.apollographql.com/docs/tutorial/introduction/">Official Apollo Full-stack GraphQL Tutorial</a> via the Apollo docs.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="738" height="1024" src="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-tutorial-space-explorer-738x1024.png" alt="" class="wp-image-6873" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-tutorial-space-explorer-738x1024.png 738w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-tutorial-space-explorer-216x300.png 216w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-tutorial-space-explorer-768x1066.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-tutorial-space-explorer.png 912w" sizes="auto, (max-width: 738px) 100vw, 738px" /></figure>



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



<p>In the written GraphQL tutorial, we build Space Explorer: an interactive app for reserving a seat on an upcoming SpaceX launch 🚀.</p>



<p>It contains a login page, list and detail-view pages, user profiles, and a cart for setting up launches.</p>



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



<p>You&#8217;ll learn how to build a full-stack GraphQL application with <em>authentication, pagination, state management,</em> and more. Specifically, you&#8217;ll learn:</p>



<ul class="wp-block-list">
<li>How to build a GraphQL schema using Apollo Server, hook it to data, and then connect to it from a client-side React applications using Apollo Client</li>



<li>How to use Apollo Client and React to fetch and display GraphQL data</li>



<li>How to use Apollo Server to build a GraphQL API</li>



<li>How to source data from a REST API</li>



<li>How to source data from a database</li>
</ul>



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



<p>If you&#8217;re ready to walk through and build Space Explorer, <a href="https://www.apollographql.com/docs/tutorial/introduction/">check out the tutorial via the Apollo docs here</a>.</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>There you have it — two great GraphQL tutorials to learn how to build fullstack apps. </p>


Learn GraphQL – Tutorials for Fullstack GraphQL


<p>Searching and filtering is a standard part of any GraphQL API. In this article, we&#8217;ll learn how to add filtering capabilities to your API by walking through a few real-world examples.</p>



<p>To learn how to handle searching and filtering on the front-end using Apollo Client, read &#8220;<a href="https://www.apollographql.com/blog/apollo-client/how-to-filter-and-search-using-variables-in-apollo-client/">How to Filter and Search using Variables in Apollo Client</a>&#8220;.</p>



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



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p><strong>Searching <em>is</em> filtering</strong>: Searching and filtering are two different ways to say the same thing. The goal is to find an item (or a list of items) that matches some sort of criteria. For the rest of this post, we&#8217;ll use the word <em>filter</em> instead of search.</p>
</blockquote>



<p>For each filtering example, we&#8217;ll take a look at the originating schema, how to write a query within it, and a resolver implementation.</p>



<p>As a reminder, GraphQL is data source-agnostic. This means that you can use whatever database technology you like to fetch and save data; for instance — SQL, ORMs, NoSQL, JSON, or in-memory data all work just fine.</p>



<p>For these examples, we&#8217;ll assume we&#8217;ve stored the data <em>in-memory</em>.</p>



<h3 class="wp-block-heading"><a href="#filtering-for-a-specific-item" aria-hidden="true" class="aal_anchor" id="filtering-for-a-specific-item"><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>Filtering for a specific item</h3>



<p>Consider the following GraphQL schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
}</code></pre>



<p>The <code>album</code> field expects an <code>ID</code> to be provided as an argument, and if found — it&#8217;ll return the <code>Album</code> type.</p>



<p>To fetch this, we could write a query that passes in an <code>id</code> and asks for the <code>album</code> with the <code>title</code>, <code>artist</code> and <code>genre</code> fields. The query could look like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAlbumById {
  album (id: &quot;1&quot;) {
    title
    genre
    artist {
      name
    }
  }
}</code></pre>



<p>And in the <a href="https://www.apollographql.com/docs/apollo-server/data/resolvers/">resolver</a> on the server, we&#8217;d pull the <code>id</code> value out from <code>args</code> and use it to filter our data.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const resolvers = {
  Query: {
    album (parent, args, context, info) {
      const { id } = args;
      return context.db.Albums.find((a) =&gt; a.id == id)
    }
  }
} </code></pre>



<h3 class="wp-block-heading"><a href="#filtering-down-a-list" aria-hidden="true" class="aal_anchor" id="filtering-down-a-list"><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>Filtering down a list</h3>



<p>Now consider our GraphQL schema had an additional field on the root <code>Query</code> type to query for a <em>list</em> of albums:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
  albums(genre: Genre): [Album]! # New
}</code></pre>



<p>With this new field, we can query for the list — optionally filtering it down using the <code>Genre</code> argument.</p>



<p>Here&#8217;s what a query might look like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetRockAlbums {
  albums (genre: &quot;Rock&quot;) {
    title
    genre
    artist {
      name
    }
  }
}</code></pre>



<p>And the resolver:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    albums (parent, args, context, info) {
      const { genre } = args;
      return context.db.Albums
	.filter((a) =&gt; a.genre == genre)
    }
  }
} </code></pre>



<h3 class="wp-block-heading"><a href="#filtering-for-items-matching-a-list" aria-hidden="true" class="aal_anchor" id="filtering-for-items-matching-a-list"><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>Filtering for items matching a list</h3>



<p>Let&#8217;s say you wanted to get a very specific set of items and you already knew their <code>ids</code>.</p>



<p>We could adjust our GraphQL schema to look more like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
  albums(genre: Genre, ids: [ID!]): [Album]! 
}</code></pre>



<p>By the way, do you notice that the parameter list is starting to get a little bit lengthy? There&#8217;s a way to clean that up, and we&#8217;ll do that soon — but first, let&#8217;s see what a query for this might look like.</p>



<p>The following query asks for albums with the ids <code>1</code>, <code>4</code>, <code>5</code>, <code>6</code>, and <code>8</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAlbumsByIds {
  albums (ids: [&quot;1&quot;, &quot;4&quot;, &quot;5&quot;, &quot;6&quot;, &quot;8&quot;]) {
    title
    genre
    artist {
      name
    }
  }
}</code></pre>



<p>To handle this sort of query in the resolver, we could write it this way:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    album (parent, args, context, info) {
      const { ids } = args;
      return context.db.Albums.filter((a) =&gt; ids.includes(a.id))
    }
  }
} </code></pre>



<h3 class="wp-block-heading"><a href="#complex-filtering-using-an-input-type" aria-hidden="true" class="aal_anchor" id="complex-filtering-using-an-input-type"><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>Complex filtering using an Input Type</h3>



<p>In the last example, we started to see that the parameter list was getting long. A better approach is to design an <em>Input Type</em> containing all the possible filtering (or sorting) options necessary, and use that as a single parameter, encapsulating all of the arguments for the field.</p>



<p>Instead of this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  album(id: ID!): Album
  albums(genre: Genre, ids: [ID!]): [Album]! 
}</code></pre>



<p>Let&#8217;s try this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type AlbumsFilters = {
  genre: Genre
  ids: [ID!]
}

type AlbumsInput = {
  filter: AlbumsFilters
}

type Query {
  album(id: ID!): Album
  albums(input: AlbumsInput): [Album]! 
}</code></pre>



<p>To handle queries for <code>albums</code> in the resolver, we&#8217;d want to take care to handle both the cases of the <code>genre</code> filter being applied, the <code>ids</code> filter being applied, and both of them being applied.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    album (parent, args, context, info) {
      const { filter } = args;
      const shouldApplyFilters = filter !== null;

      let albums = context.db.Albums;

      if (!shouldApplyFilters) {
	return albums;
      }

      const shouldApplyGenreFilter = filter.genre !== null;
      const shouldApplyIdsFilter = filter.ids;

      if (shouldApplyGenreFilter) {
	albums = albums
          .filter((a) =&gt; a.genre === filter.genre)
      }

      if (shouldApplyIdsFilter) {
	albums = albums.filter((a) =&gt; ids.includes(a.id))
      }
		
      return albums;
    }
  }
} </code></pre>



<p>While this <em>does</em> add complexity to the resolver, it makes the querying experience much more robust.</p>



<p>Using the <em>Input Type</em> pattern, you can incrementally add more filtering (or sorting) options to your API like:</p>



<ul class="wp-block-list">
<li><strong>Filtering between ranges (greater than, less than, equal)</strong></li>



<li><strong>Conditional filtering (and, or, not, exists, etc)</strong></li>



<li><strong>Any other filtering criteria you can think of</strong></li>
</ul>



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



<p>We just walked through a few examples of how to add filter functionality to your GraphQL API. You should be all set to implement filtering in your own GraphQL API.</p>



<h3 class="wp-block-heading"><a href="#develop-your-graphql-api-with-apollo-explorer" aria-hidden="true" class="aal_anchor" id="develop-your-graphql-api-with-apollo-explorer"><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>Develop Your GraphQL API with Apollo Explorer</h3>



<p>Apollo Explorer is a free cloud GraphQL IDE that we built from the ground up, <strong>specifically for GraphQL developers</strong>.</p>



<p>The Explorer comes with productivity-boosting features like one-click query building, intelligent search, and the ability to extract variables and fragments.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="954" height="544" src="https://wp.apollographql.com/wp-content/uploads/2021/03/point-and-click-1.gif" alt="" class="wp-image-6849"/></figure>



<p>Apollo Explorer also comes with <a href="https://www.apollographql.com/docs/studio/dev-graphs/">development graphs</a>, which enables you to build, test, and document your schema changes locally, as well as preview graph changes in local branches and PRs.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="354" src="https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled.png" alt="" class="wp-image-6851" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-300x104.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/Untitled-768x266.png 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>To use Apollo Explorer, head over to <a href="https://studio.apollographql.com/dev?referrer=blog">studio.apollographql.com/dev</a> and get started with your first development graph.</p>



<p>Happy querying!</p>


GraphQL Search and Filter – How to search and filter results with GraphQL


<p>When building out APIs on the web, we&#8217;ll often find ourselves in the situation where we need to quickly verify that the route or API call we just created works the way we intend it to.</p>



<p>If you&#8217;re not using <a href="https://studio.apollographql.com/dev?referrer=blog">Apollo Explorer</a> to test your GraphQL API (our free GraphQL IDE in Apollo Studio), another option is Postman. It works as a great tool for testing <em>any</em> HTTP endpoint &#8211; that means GraphQL too.</p>



<p>In this short post, we&#8217;ll walk through how to manually test your GraphQL API using Postman.</p>



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



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



<ul class="wp-block-list">
<li>You have Git installed</li>



<li>You have NPM and Node.js (8+) installed</li>



<li>You have the Postman Agent installed or a Postman account</li>



<li>You understand the basics of GraphQL (you can read &#8220;<a href="https://www.apollographql.com/blog/what-is-graphql-graphql-introduction/">What is GraphQL? GraphQL Introduction</a>&#8221; to get up to speed)</li>
</ul>



<h3 class="wp-block-heading"><a href="#clone-install-and-start-the-server" aria-hidden="true" class="aal_anchor" id="clone-install-and-start-the-server"><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>Clone, install, and start the server</h3>



<p>We&#8217;re going to use the discography example from <a href="https://github.com/apollographql/apollo-server-starter">apollo-server-starter</a>.</p>



<p>To pull the code from GitHub and start the server, paste the following command into a terminal on your machine.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">git clone https://github.com/apollographql/apollo-server-starter
cd apollo-server-starter 
npm install &amp;&amp; npm run start:example discography</code></pre>



<p>If you see the following, your server is up and running:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">🚀 Server ready at http://localhost:4000/</code></pre>



<h3 class="wp-block-heading"><a href="#review-the-schema" aria-hidden="true" class="aal_anchor" id="review-the-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>Review the schema</h3>



<p>Let&#8217;s review our schema before we get into it. In the discography schema, you&#8217;ll find definitions for albums, tracks, and artists — and two queries that return either all albums, or a specific one.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">enum Genre {
  Pop,
  Rock,
  Alternative
  HipHop
}

type Track {
  title: String!
  number: Int!
}

type Artist {
  name: String!
}

type Album {
  title: String!
  artist: Artist!
  tracks: [Track!]!
  genre: Genre!
}

type Query {
  albums(genre: Genre): [Album!]!
  album(title: String!): Album
}</code></pre>



<h2 class="wp-block-heading"><a href="#writing-a-graphql-request-with-postman" aria-hidden="true" class="aal_anchor" id="writing-a-graphql-request-with-postman"><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>Writing a GraphQL Request with Postman</h2>



<p>The first query we&#8217;ll write is one that <strong>fetches</strong> <strong>all albums</strong>.</p>



<p>We begin by opening postman and selecting the option to write a new query.</p>



<p>Next, we begin the query by first writing the URL of the request. In our case, that&#8217;ll be @ <code>http://localhost:4000/</code>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1025" height="336" src="https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.37.17_PM.png" alt="" class="wp-image-6824" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.37.17_PM.png 1025w, https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.37.17_PM-300x98.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.37.17_PM-768x252.png 768w" sizes="auto, (max-width: 1025px) 100vw, 1025px" /></figure>



<p>Then, we&#8217;ll change the method to POST — this is necessary since all GraphQL operations work on top of the HTTP POST method.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="351" src="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-post-1024x351.png" alt="" class="wp-image-6826" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-post-1024x351.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-post-300x103.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-post-768x263.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-post.png 1026w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>And then we&#8217;ll formulate the body of the request.</p>



<p>Click the selection that says <em>Body</em> and then choose <em>GraphQL</em> in the selection list below it. You&#8217;ll be presented with a <em>Query</em> and a <em>GraphQL Variables</em> window.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="457" src="https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.38.45_PM-1024x457.png" alt="" class="wp-image-6828" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.38.45_PM-1024x457.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.38.45_PM-300x134.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.38.45_PM-768x343.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/03/Screen_Shot_2021-03-17_at_6.38.45_PM.png 1026w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Within this <em>Query</em> window, let&#8217;s write our query. Write or paste this code into it.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAllAlbums {
  albums {
    title 
    artist {
      name
    }
    tracks {
      title 
      number
    }
    genre
  }
}</code></pre>



<p>Finally, let&#8217;s click the blue <em>Send</em> button at the top right.</p>



<p>It all goes well, you should see the query results in the Response window at the bottom of the page.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="619" src="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-request-1024x619.png" alt="" class="wp-image-6830" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-request-1024x619.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-request-300x181.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-request-768x464.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-request.png 1077w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>That&#8217;s how you write GraphQL queries using Postman!</p>



<h3 class="wp-block-heading"><a href="#including-variables" aria-hidden="true" class="aal_anchor" id="including-variables"><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>Including variables</h3>



<p>Just as often as we need to write queries that return data, we need to pass in variables to apply sorting and filtering through our data so that we can see relevant data.</p>



<p>To add GraphQL variables, we use the window of the same title on the right hand side.</p>



<p>Let&#8217;s use the <code>albums(genre: Genre!)</code> query and filter in on the list of albums by a particular genre.</p>



<p>First, we modify the query by giving it the the <em>Variable Definitions</em> necessary to make this query. Paste the following into the Query window.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAllAlbums ($genre: Genre) {
  albums (genre: $genre) {
    title 
    artist {
      name
    }
    tracks {
      title 
      number
    }
    genre
  }
}</code></pre>



<p>Then, in the GraphQL Variables window, we need to supply it with the data that we want to use as arguments.</p>



<p>Let&#8217;s filter in on albums with the <code>HipHop</code> genre. Paste the following into the GraphQL Variables window.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
    &quot;genre&quot;: &quot;HipHop&quot;
}</code></pre>



<p>Your windows should look like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="510" src="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-looks.png" alt="" class="wp-image-6832" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-looks.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-looks-300x149.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-looks-768x383.png 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>And when you&#8217;re ready, click the blue <em>Send</em> button again.</p>



<p>Looking at the results in the <em>Response</em> window at the bottom, it looks like we only got a single album back: &#8220;<em>Paul&#8217;s Boutique</em>&#8221; (good album 👍 ).</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1017" height="621" src="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-paul.png" alt="" class="wp-image-6834" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-paul.png 1017w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-paul-300x183.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/graphql-postman-paul-768x469.png 768w" sizes="auto, (max-width: 1017px) 100vw, 1017px" /></figure>



<p>And that&#8217;s all there is to it.</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>When you&#8217;re building out your GraphQL API, it&#8217;s a good idea to use a GraphQL IDE to test out your GraphQL operations. Keeping those feedback loops tight helps so that you can verify that things are working the way they should be. And since GraphQL works on top of HTTP, you can use Postman to manually test your API.</p>



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



<p><a href="https://studio.apollographql.com/dev?referrer=blog">Apollo Explorer</a> is a free cloud GraphQL IDE that we built from the ground up, <strong>specifically for GraphQL developers</strong>.</p>



<p>The Explorer comes with productivity-boosting features like one-click query building, intelligent search, and the ability to extract variables and fragments.</p>



<figure class="wp-block-image size-large is-style-default"><img loading="lazy" decoding="async" width="954" height="544" src="https://wp.apollographql.com/wp-content/uploads/2021/03/point-and-click.gif" alt="" class="wp-image-6836"/></figure>



<p>Apollo Explorer also comes with <a href="https://www.apollographql.com/docs/studio/dev-graphs/">development graphs</a>, which enables you to build, test, and document your schema changes locally, as well as preview graph changes in local branches and PRs.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="354" src="https://wp.apollographql.com/wp-content/uploads/2021/03/apollo-studio-apollo-explorer-1.png" alt="" class="wp-image-6840" srcset="https://wp.apollographql.com/wp-content/uploads/2021/03/apollo-studio-apollo-explorer-1.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/03/apollo-studio-apollo-explorer-1-300x104.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/03/apollo-studio-apollo-explorer-1-768x266.png 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>To use Apollo Explorer, head over to <a href="https://studio.apollographql.com/dev?referrer=blog">studio.apollographql.com/dev</a> to get started with your first development graph.</p>



<p>Happy querying!</p>


How to use GraphQL with Postman – Postman testing with GraphQL

Building a GraphQL API – GraphQL API example


<p>One of the fastest ways to get up and running with GraphQL is to install Apollo Server as <em>middleware</em> on your new or existing HTTP server.</p>



<p>In this short post, we demonstrate how to use Apollo Server to create a GraphQL server with Express.js using the <a href="https://www.npmjs.com/package/apollo-server-express">apollo-server-express</a> package. At the end, we&#8217;ll discuss the tradeoffs of this approach.</p>



<h2 class="wp-block-heading"><a href="#using-apollo-server-with-express" aria-hidden="true" class="aal_anchor" id="using-apollo-server-with-express"><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 Apollo Server with Express</h2>



<p>Let&#8217;s start with the dependencies.</p>



<h3 class="wp-block-heading"><a href="#install-dependencies" aria-hidden="true" class="aal_anchor" id="install-dependencies"><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>Install dependencies</h3>



<p>You&#8217;ll need the <code>apollo-server-express</code> and <code>graphql</code> packages.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">npm install apollo-server-express graphql --save</code></pre>



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



<p>The way we set up a GraphQL server using <code>apollo-server-express</code> is very similar to the barebones approach of using the <code>apollo-server</code> package.</p>



<p>The only difference is that we apply the Apollo Server instance as middleware to an Express HTTP instance with <code>server.applyMiddleware({ app })</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const express = require(&#039;express&#039;);
const { ApolloServer, gql } = require(&#039;apollo-server-express&#039;);

// Construct a schema, using GraphQL schema language
const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// Provide resolver functions for your schema fields
const resolvers = {
  Query: {
    hello: () =&gt; &#039;Hello world!&#039;,
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

const app = express();
server.applyMiddleware({ app });

app.listen({ port: 4000 }, () =&gt;
  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
);
﻿</code></pre>



<p>Your GraphQL API should be running at <code>http://localhost:4000/graphql</code>.</p>



<h2 class="wp-block-heading"><a href="#tradeoffs-of-using-apollo-server-as-graphql-middleware" aria-hidden="true" class="aal_anchor" id="tradeoffs-of-using-apollo-server-as-graphql-middleware"><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>Tradeoffs of using Apollo Server as GraphQL middleware</h2>



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



<p>One neat thing about using <code>apollo-server-express</code> instead of <code>apollo-server</code> is that we can serve both REST and GraphQL at the same time using Express.</p>



<p>Serving a GraphQL server <em>within</em> Express also maintains our ability to use Node.js middleware for common problems like rate-limiting, security, and authentication.</p>



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



<p>Using <code>apollo-server-express</code> involves a little bit more boilerplate than merely using <code>apollo-server</code>. However, since <code>apollo-server</code> is just a wrapper around <code>apollo-server-express</code>, there shouldn&#8217;t be any performance concerns. </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>We learned how to set up a GraphQL server with <code>apollo-server-express</code> and discussed some of the tradeoffs. If you&#8217;re using a different middleware library like Restify, Hapi, Koa, or Lambdas, <a href="https://www.apollographql.com/docs/apollo-server/v1/servers/express/">check out our docs</a> for details on the other GraphQL API integrations.</p>


Using Express with GraphQL – How to create a GraphQL server with Node.js/Express


<p>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>But it is not for everyone.</p>



<p>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>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><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>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>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>But schema stitching isn&#8217;t easy.</p>



<p>Using my simple example of Product and Basket types, what you want is the following schema where the <code>Basket</code> type contains an items field that returns an array of <code>Product</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># 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>​But that won&#8217;t work. The <code>Basket</code> service has no knowledge of <code>Products</code> and probably only knows about the ID of the products in the basket.</p>



<p>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>Basket</code> service call the <code>Product</code> service to get the <code>Product</code> information.</li></ul>



<p>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>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>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>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>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>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>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>Refactoring our example from earlier:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># 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>The Basket service defines a <code>Basket</code> type with an items field of <code>BasketItem</code> that defines the quantity of a given item. But where are the products?</p>



<p>Well, the Product service now not only defines the <code>Product</code> type, but it also extends the <code>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>How does it achieve this? At a high level, the <code>@key</code> directives after the various types define the externally referenceable fields used to link the types together.</p>



<p>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>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>Basket</code> data and the Product service handles all requests for <code>Product</code> data, even when some of those requests are&nbsp;<em>actually</em>&nbsp;made to resolve the <code>Product</code> data for the items in the <code>Basket</code>.</p>



<p>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>Basket</code>.</p>



<p>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>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></p>


the evolution of graphql at scale by andy roberts

The Evolution of GraphQL at Scale


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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

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

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

class LocalInMemoryCache implements ICache {

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

/**
* Your Redis cache
*/

class RedisCache implements ICache {
 private redisConnection: Redis;

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

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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


Caching Strategies in a Federated GraphQL Architecture


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


9 Lessons From a Year of Apollo Federation


<p>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>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>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>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>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>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>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>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>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>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>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>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>In the above we have introduced two <strong>schema services</strong>: <code>Product</code> and <code>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>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>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>The <code>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>Review</code> service, then they can be integrated into the gateway directly.</p>



<p>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>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>My only advice, no matter what approach you take, is to start small.</p>



<p>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>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>Recently, I needed to create a proxy to a third party API in our GraphQL Federation schema but didn’t want to spin up a new service just for this. This blog post explains how to use local schemas inside the Apollo Federation Gateway.</p>



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



<p>At&nbsp;<a href="https://team.pollen.co/">work</a>,&nbsp;we use the Prismic <a href="https://en.wikipedia.org/wiki/Content_management_system">CMS</a> to power the content of our site (at least most of it). We are currently working on a new project that is using Apollo Federation as our Gateway<sup><a href="https://patrick.wtf/posts/apollo-federation-local-services#fn-1">1</a></sup>.</p>



<p>We wanted to add the Prismic API to our Gateway, so as to provide a single graph to our users on the frontend (see <a href="https://principledgraphql.com/">PrincipledGraphQL</a>). Unfortunately, when a GraphQL API doesn’t provide support for Apollo Federation, things aren’t as easy as specifying the service in Apollo’s services list.</p>



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



<p>Let’s supposed that we have one Apollo federation that’s consuming one service for the time being.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const gateway = new ApolloGateway({
  serviceList: [{
    name: &quot;products&quot;,
    url: &quot;http://localhost:4002&quot;
  }],
});
const server = new ApolloServer({ gateway });
server.listen();</code></pre>



<p>As you can see, the ApolloGateway requires a list of GraphQL services as objects with a name and a URL. This is a bit unfortunate as this means that using a local schema doesn’t work by default.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Note:</strong>&nbsp;we can’t use Prismic’s GraphQL API directly as they don’t provide the necessary fields for federation. In addition to that, they also use GET requests instead of POST requests for the API call, and ApolloGateway always sends POST requests. Lastly, I wanted to keep the code simple. I’ll be happy to provide an example repo with Prismic if it’s needed. Drop me a&nbsp;<a href="https://patrick.wtf/posts/(https://countries.trevorblades.com/">tweet</a>&nbsp;in that case!</p></blockquote>



<h2 class="wp-block-heading"><a href="#what-can-we-do-to-make-this-work" aria-hidden="true" class="aal_anchor" id="what-can-we-do-to-make-this-work"><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 can we do to make this work?</h2>



<p>What makes Federation work with multiple services is the Apollo Gateway, which basically acts as the glue between the services. It knows how to compose the schemas and how to create a query plan for executing a query.</p>



<p>From my understanding of the source code, Apollo Gateway seems to support local services, but, as mentioned in this&nbsp;<a href="https://github.com/apollographql/apollo-server/issues/3250">GitHub Issue</a>&nbsp;it doesn’t allow to support both local and remote services at the same time by default.</p>



<p>Fortunately for us, we can use&nbsp;<code>buildService</code>&nbsp;to provide create a custom DataSource for our remote schema.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>DataSource is what Apollo Gateway uses to fetch data from a service. That means we can create a DataSource that proxies the requests to Prismic.</p></blockquote>



<p>We will be using&nbsp;<a href="https://countries.trevorblades.com/">Trevor Blades’ Countries API</a>, a public GraphQL API that doesn’t support Apollo Federation.</p>



<p>So,&nbsp;<code>buildService</code>&nbsp;is called for each service specified in the&nbsp;<code>serviceList</code>&nbsp;configuration parameter for Apollo Gateway. Let’s go and update that to have a service for the countries service:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const gateway = new ApolloGateway({
  serviceList: [
    { name: &#039;products&#039;, url: &#039;http://localhost:4002&#039; },
    { name: &#039;countries&#039;, url: &#039;http://countries&#039; },
  ]
});
const server = new ApolloServer({ gateway });
server.listen();</code></pre>



<p>The only caveat that we have is that we have need to provide a&nbsp;<code>url</code>&nbsp;for our service, even it is fake.</p>



<p>The next step is to provide a&nbsp;<code>buildService</code>&nbsp;function, which looks like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const gateway = new ApolloGateway({
  serviceList: [
    { name: &quot;products&quot;, url: &quot;http://localhost:4002&quot; },
    { name: &quot;countries&quot;, url: &quot;http://countries&quot; },
  ],
  buildService: ({ url }) =&gt; {
    if (url === &quot;http://countries&quot;) {
      return new LocalGraphQLDataSource(getCountriesSchema());
    } else {
      return new RemoteGraphQLDataSource({
        url,
      });
    }
  },
});
const server = new ApolloServer({ gateway });
server.listen();</code></pre>



<p>Ok, the last step is to create the function that will return the schema for the countries service. Similar to&nbsp;<code>RemoteGraphQLDataSource</code>&nbsp;Apollo Gateway also provides a&nbsp;<code>LocalGraphQLDataSource</code>&nbsp;which accepts a&nbsp;<code>schema</code>&nbsp;as a parameter instead of a&nbsp;<code>url</code>. This means that we can provide our own schema!</p>



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



<p>Now that we know we can provide our own schema to Apollo Gateway, how can we proxy to an existing schema? We could do this manually, but it would take a bit of time, luckily for us, there’s a package called&nbsp;<a href="https://www.graphql-tools.com/"><code>graphql-tools</code></a>&nbsp;that allows using a&nbsp;<a href="https://www.graphql-tools.com/docs/remote-schemas">remote schema</a>&nbsp;as if it were local.</p>



<p>In addition to that, we also need to use&nbsp;<a href="https://github.com/0xR/graphql-transform-federation"><code>graphql-transform-federation</code></a>&nbsp;to provide the required fields for Apollo Federation. Let’s see how our function looks like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const executor = async ({ document, variables }) =&gt; {
    const query = print(document);
    const fetchResult = await fetch(&quot;https://countries.trevorblades.com/&quot;, {
        method: &quot;POST&quot;,
        headers: {
            &quot;Content-Type&quot;: &quot;application/json&quot;,
        },
        body: JSON.stringify({ query, variables }),
    });
    return fetchResult.json();
};
const getCountriesSchema = async () =&gt; {
    const schema = wrapSchema({
        schema: await introspectSchema(executor),
        executor,
    });
    return transformSchemaFederation(schema, {
        Query: {
            extend: true,
        },
    });
};</code></pre>



<p>There are a few things going on here. First, we have a function called&nbsp;<code>executor</code>. This is our core function that proxies the calls to the <code>countries</code> service; it&#8217;s not doing anything special. It gets the document and variables and sends them to the <code>countries</code> services. For Prismic, we’d add headers for authentication and change the request to be a&nbsp;<code>GET</code>. But the rest would pretty much be the same.</p>



<p>Finally, the last piece of the puzzle is&nbsp;<code>getCountriesSchema&nbsp;</code>: it uses the utilities from&nbsp;<code>graphql-tools</code>&nbsp;and&nbsp;<code>graphql-transform-federation&nbsp;</code>&nbsp;to create a proxy schema with support for Federation.</p>



<p><code>getCountriesSchema</code>&nbsp;uses&nbsp;<code>wrapSchema</code>&nbsp;to create a schema based on our Countries GraphQL API. We need to pass a schema, an executor, and some optional transforms. We do not use any transform here, but one use case is to rename the types so they don’t conflict with other services.</p>



<p>Finally, it calls&nbsp;<code>transformSchemaFederation</code>&nbsp;to obtain a Federation compatible schema, the only option we are passing here is telling Federation that this schema is extending the&nbsp;<code>Query</code>&nbsp;type, so all the fields provided here will be composed into the federated schema. We can also pass more options here, but at the moment we didn’t need that.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Note:</strong>&nbsp;the code in the example is a bit broken as we are not awaiting&nbsp;<code>getCountriesSchema&nbsp;</code>&nbsp;in our&nbsp;<code>buildServices</code>, the final code provided in the&nbsp;<a href="https://github.com/patrick91/apollo-federation-local-services/blob/main/server.js#L11">git repo has the correct solution</a>, I wanted to keep the code example simple here.</p></blockquote>



<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>As you can see, you need a little bit of code to proxy a non-federated GraphQL service with Apollo Gateway, but it&#8217;s not too bad. I think it&#8217;s pretty cool we can do this as we can move the code that deals with multiple schemas from our clients to our gateway, simplifying how they fetch data.</p>



<p>Also,&nbsp;<code>graphql-transform-federation</code>&nbsp;allows specifying a Federation configuration. This makes it possible to use Apollo Federation features to extend types with a non-federated service, which can definitely make the schema easier to use.</p>



<p>To see a fully working example of this head to the&nbsp;<a href="https://github.com/patrick91/apollo-federation-local-services">example repo I’ve written for this blog post</a>.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Note:</strong>&nbsp;all of this post might be deprecated in the future when&nbsp;project constellation&nbsp;gets released to the public. It&#8217;s a new feature that will enable consolidation of services that don&#8217;t have the (currently) required fields. In the meantime, feel free to try this approach.</p></blockquote>


Using Apollo Federation with Local Schemas


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>A Better Way to do CI For GraphQL</p></blockquote>



<p>When deploying code, you want to be sure that nothing will blow up when things go live. To prevent downtime, it’s a good practice to use CI (continuous integration) to run tests, checks, and ensure your app is fully ready to hit production.<br><br>If you’re running GraphQL in production, the <em>last</em> thing you want is a <strong>schema change </strong>to break things for your users.<br><br>Here at Apollo, we’ve taken stock of every way schema changes could cause downtime, and <strong>we’re delighted to announce a new and improved schema check to ensure your GraphQL layer is evolving smoothly 🎉</strong></p>



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



<p>Using the <a href="https://www.apollographql.com/docs/devtools/cli/">Apollo CLI</a>, you can ensure changes made to your schema are backwards compatible by checking it against <em>real production traffic</em>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1671" height="945" src="https://wp.apollographql.com/wp-content/uploads/2020/10/Screen-Recording-2020-09-30-at-11.07.42-PM.gif" alt="" class="wp-image-4806"/></figure>



<p>We’ve redesigned our schema checks experience to prioritize giving you the most important information. Schema checks help you understand how a change will affect your <em>real-life clients.</em> This release comes with a few long-awaited additions:</p>



<ul class="wp-block-list"><li><strong>Better visibility</strong>: Understand not only <em>which</em> clients are affected, but also <em>how</em>. Schema checks help you determine if an operation won’t run with the new schema.</li><li><strong>Change-level and operation-level overrides</strong>: For dealing with more nuanced cases.</li><li><strong>Better UX</strong>: A visual update that shows usage of your affected operation and provides valuable forensics.</li></ul>



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



<p>We’ve also made it possible for teams to configure key settings for schema checks in a central place (see the <em>Check Configurations</em> page in <a href="https://www.apollographql.com/docs/studio/getting-started/">Apollo Studio</a>). Using this central configuration, teams can align on best practices (such as a standard deprecation lifecycle) and share information about deprecated clients and operations.</p>



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



<p>Want to safely evolve your graph in production? Read the docs on <a href="https://www.apollographql.com/docs/studio/schema-checks">schema checks</a> to learn more and see how to try it out!</p>


Schema Checks: Introducing the New GraphQL CI Tool In Apollo Studio

Building a Portable Apollo Server Config


<p>Apollo Graph Manager&#8217;s schema registry powers a ton of features that help you explore, maintain, and monitor your data graph. These features are at their <em>most</em> powerful when the schema you register with Apollo stays up to date with the schema you run in production. To help teams keep their schemas synced, we&#8217;re excited to announce a new Graph Manager feature called <strong>schema reporting</strong>.</p>



<p>Schema reporting enables Apollo Server (or any other GraphQL server!) to automatically register its schema with <a href="https://www.apollographql.com/docs/graph-manager/">Graph Manager</a> on startup. Previously, updating your registered schema required running an Apollo CLI command, which is easy to forget if it isn&#8217;t part of your continuous delivery pipeline.</p>



<p>By registering your schema automatically, you can:</p>



<ul class="wp-block-list"><li>Track your <em>complete</em> schema history over time</li><li>Share and iterate on development schemas with your team before they land in production</li><li>Set up continuous integration to <a href="https://www.apollographql.com/docs/graph-manager/schema-validation/">check schema changes against past traffic</a></li><li>Get up-to-date autocomplete and timing information in your IDE with Apollo&#8217;s <a href="https://www.apollographql.com/docs/devtools/editor-plugins/#gatsby-focus-wrapper">VS Code extension</a></li></ul>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Note:</strong> Schema reporting doesn&#8217;t currently support graphs that use Apollo Federation. If you&#8217;re running a federated graph, check out <a href="https://www.apollographql.com/docs/graph-manager/managed-federation/setup/">Setting up managed federation</a>.</p></blockquote>



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



<p><strong>The complete instructions for turning on schema reporting in Apollo Server are in the <a href="https://www.apollographql.com/docs/graph-manager/schema-registry/#automatic-registration-recommended" target="_blank" rel="noreferrer noopener">Apollo docs</a>.</strong> Here are the high-level steps:</p>



<ol class="wp-block-list"><li><a rel="noreferrer noopener" href="https://engine.apollographql.com/" target="_blank">Sign up for Graph Manager</a> and create your graph if you haven&#8217;t yet.</li><li>Obtain an API key from Graph Manager.</li><li>In your server&#8217;s environment, set your API key as the value of the <code>APOLLO_KEY</code> environment variable.</li><li>Set the <code>engine.reportSchema</code> option to <code>true</code> in your <code>ApolloServer</code> constructor, like this:</li></ol>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const server = new ApolloServer({
  // ...other options...
  engine: {
    reportSchema: true,
  }
});</code></pre>



<p>That&#8217;s it! Now every time your server starts up, it automatically registers its current schema to your graph. And if you perform a rolling deployment of a new schema version, Graph Manager intelligently waits to register the new schema until every server instance stops reporting the<em> </em>previous<em> </em>one.</p>



<p>To learn about all of the configuration options for schema reporting, check out <a href="https://www.apollographql.com/docs/graph-manager/schema-registry/#automatic-registration-recommended">the docs</a>.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Note:</strong> By default, schema reporting registers to your graph&#8217;s default variant, which is named <code>current</code>. To register to a different variant (such as <code>feature-123</code> or <code>staging</code>), set the <code>APOLLO_GRAPH_VARIANT</code> environment variable to the name of the variant you want to register to.</p></blockquote>



<h2 class="wp-block-heading"><a href="#other-graphql-servers" aria-hidden="true" class="aal_anchor" id="other-graphql-servers"><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>Other GraphQL Servers</h2>



<p>Not using Apollo Server? No problem! Any GraphQL server can implement the schema reporting protocol, which is <a href="https://deploy-preview-892--graph-manager-docs.netlify.app/docs/graph-manager/schema-reporting-protocol/">publicly documented</a> (as is Apollo Server&#8217;s <a href="https://github.com/apollographql/apollo-server/blob/master/packages/apollo-engine-reporting/src/schemaReporter.ts">reference implementation</a>). We want it to be as straightforward as possible to add schema reporting to whichever GraphQL server you use, and we’d love to <a href="mailto:gravity@apollographql.com">support you</a> in any way we can.<br></p>



<p>The Apollo team is committed to building tools that make it easy for you and your team to develop quickly and safely with GraphQL. If you have feedback on schema reporting or suggestions on how we can improve your team’s workflows, <a href="mailto:support@apollographql.com">let us know</a>!</p>


Register Schema Changes Automatically with Schema Reporting


<p><strong><a href="https://github.com/accounts-js/accounts">accounts-js</a>&nbsp;is a fullstack authentication and accounts-management for Javascript.</strong>&nbsp;We provide you with a set of tools to authenticate and manage your users in your application. These tools work with REST, GraphQL and are database agnostic.</p>



<p>We will implement the Authentication GraphQL API in NodeJS using accounts-js and Apollo. At the end of this article, our server will be able to sign up new users, allow the users to login and authenticate them to protect some restricted information.</p>



<p><em>At the end of this post, you can find a link to a repository containing the sources.</em></p>



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



<p>For this project, you will need to have nodejs and mongodb installed on your system.</p>



<h3 class="wp-block-heading"><a href="#setup-the-node-project" aria-hidden="true" class="aal_anchor" id="setup-the-node-project"><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>Setup the node project</h3>



<p>Let&#8217;s start by creating our NodeJS project. Create a new folder named&nbsp;<code>accounts-js-server</code>, all the project files should be inside this folder. Let&#8217;s initialize our new project using&nbsp;<code>npm</code>&nbsp;(you can use&nbsp;<code>yarn</code>&nbsp;if you prefer):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">npm init</code></pre>



<p>Now, let&#8217;s add the dependencies we need to setup our Apollo GraphQL server.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install apollo-server graphql</code></pre>



<p>Create a new&nbsp;<code>index.js</code>&nbsp;file (to make this tutorial simpler all our code will be in a single file) and add this code to setup the Apollo server.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const { ApolloServer, gql } = require(&#039;apollo-server&#039;);

const typeDefs = gql`
  type Query {
    # This query will be protected so only authenticated users can access it
    sensitiveInformation: String
  }
`;

const resolvers = {
  Query: {
    sensitiveInformation: () =&gt; &#039;Sensitive info&#039;,
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

// The `listen` method launches a web server.
server.listen().then(({ url }) =&gt; {
  console.log(`🚀  Server ready at ${url}`);
});</code></pre>



<p>Now let&#8217;s start the server to make sure everything is working as expected.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">node index.js</code></pre>



<p>In your console you should see:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">🚀  Server ready at http://localhost:4000/</code></pre>



<p>Our GraphQL server is now ready, it&#8217;s time to add accounts-js!</p>



<h3 class="wp-block-heading"><a href="#setup-accounts-js" aria-hidden="true" class="aal_anchor" id="setup-accounts-js"><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>Setup accounts-js</h3>



<p>First, we will setup mongoose and connect to our database.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install @accounts/mongo mongoose</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const mongoose = require(&#039;mongoose&#039;);
const { Mongo } = require(&#039;@accounts/mongo&#039;);

// We connect mongoose to our local mongodb database
mongoose.connect(&#039;mongodb://localhost:27017/accounts-js-server&#039;, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

// We tell accounts-js to use the mongo connection
const accountsMongo = new Mongo(mongoose.connection);</code></pre>



<p>Then, we add the accounts-js server dependencies.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install @accounts/server @accounts/password</code></pre>



<ul class="wp-block-list"><li><code>@accounts/server</code>: The accounts-js core dependency.</li><li><code>@accounts/password</code>: The accounts-js password service, it expose a set of function to manage and authenticate users using email + password.</li></ul>



<p>It&#8217;s time to setup the accounts-js server configuration</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const { AccountsServer } = require(&#039;@accounts/server&#039;);
const { AccountsPassword } = require(&#039;@accounts/password&#039;);

const accountsPassword = new AccountsPassword({
  // You can customise the behavior of the password service by providing some options
});

const accountsServer = new AccountsServer(
  {
    // We link the mongo adapter we created in the previous step to the server
    db: accountsMongo,
    // Replace this value with a strong random secret
    tokenSecret: &#039;my-super-random-secret&#039;,
  },
  {
    // We pass a list of services to the server, in this example we just use the password service
    password: accountsPassword,
  }
);</code></pre>



<p>Then, we add the accounts-js graphql dependencies.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install @accounts/graphql-api @graphql-toolkit/schema-merging @graphql-modules/core</code></pre>



<ul class="wp-block-list"><li><code>@accounts/graphql-api</code>: The transport layer exposing all the queries and mutations accounts-js provide.</li><li><code>@graphql-toolkit/schema-merging</code>: Expose a set of tools that will help us to merge our schemas.</li><li><code>@graphql-modules/core</code>: An internal dependency that accounts-js use to manage his graphql schema and resolvers.</li></ul>



<p>Let&#8217;s merge the accounts-js GraphQL schema and our schema, so the user can access it</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

// Add makeExecutableSchema to the imported variables
const { ApolloServer, gql, makeExecutableSchema } = require(&#039;apollo-server&#039;);
const { mergeTypeDefs, mergeResolvers } = require(&#039;@graphql-toolkit/schema-merging&#039;);
const { AccountsModule } = require(&#039;@accounts/graphql-api&#039;);

// We generate the accounts-js GraphQL module
const accountsGraphQL = AccountsModule.forRoot({ accountsServer });

// A new schema is created combining our schema and the accounts-js schema
const schema = makeExecutableSchema({
  typeDefs: mergeTypeDefs([typeDefs, accountsGraphQL.typeDefs]),
  resolvers: mergeResolvers([accountsGraphQL.resolvers, resolvers]),
  schemaDirectives: {
    ...accountsGraphQL.schemaDirectives,
  },
});

// When we instantiate our Apollo server we use the schema and context properties
const server = new ApolloServer({
  schema,
  context: accountsGraphQL.context,
});</code></pre>



<p>At the end, our file should look like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const { ApolloServer, gql, makeExecutableSchema } = require(&#039;apollo-server&#039;);
const mongoose = require(&#039;mongoose&#039;);
const { Mongo } = require(&#039;@accounts/mongo&#039;);
const { mergeTypeDefs, mergeResolvers } = require(&#039;@graphql-toolkit/schema-merging&#039;);
const { AccountsServer } = require(&#039;@accounts/server&#039;);
const { AccountsPassword } = require(&#039;@accounts/password&#039;);
const { AccountsModule } = require(&#039;@accounts/graphql-api&#039;);

// We connect mongoose to our local mongodb database
mongoose.connect(&#039;mongodb://localhost:27017/accounts-js-server&#039;, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

const accountsMongo = new Mongo(mongoose.connection);

const typeDefs = gql`
  type Query {
    # This query will be protected so only authenticated users can access it
    sensitiveInformation: String
  }
`;

const resolvers = {
  Query: {
    sensitiveInformation: () =&gt; &#039;Sensitive info&#039;,
  },
};

const accountsPassword = new AccountsPassword({});

const accountsServer = new AccountsServer(
  {
    db: accountsMongo,
    // Replace this value with a strong secret
    tokenSecret: &#039;my-super-random-secret&#039;,
  },
  {
    password: accountsPassword,
  }
);

// We generate the accounts-js GraphQL module
const accountsGraphQL = AccountsModule.forRoot({ accountsServer });

// A new schema is created combining our schema and the accounts-js schema
const schema = makeExecutableSchema({
  typeDefs: mergeTypeDefs([typeDefs, accountsGraphQL.typeDefs]),
  resolvers: mergeResolvers([accountsGraphQL.resolvers, resolvers]),
  schemaDirectives: {
    ...accountsGraphQL.schemaDirectives,
  },
});

const server = new ApolloServer({ schema, context: accountsGraphQL.context });

// The `listen` method launches a web server.
server.listen().then(({ url }) =&gt; {
  console.log(`🚀  Server ready at ${url}`);
});</code></pre>



<p>If we restart our server and visit http://localhost:4000/, we should see that the accounts-js queries and mutations are merged with our schema. Our authentication server is now ready 🚀.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="632" src="https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-1024x632.png" alt="" class="wp-image-2160" srcset="https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-1024x632.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-300x185.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-768x474.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-1200x740.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2.png 1277w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h3 class="wp-block-heading"><a href="#creating-our-first-user" aria-hidden="true" class="aal_anchor" id="creating-our-first-user"><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>Creating our first user</h3>



<p>Inside the GraphQL Playground, let&#8217;s execute the following mutation:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation {
  createUser(
    user: { email: &quot;john.doe@john.com&quot;, password: &quot;superSecurePassword&quot; }
  )
}</code></pre>



<p>Congrats, our first user has been created 👏!</p>



<p>If you take a look at the&nbsp;<code>users</code>&nbsp;collection inside mongodb you should see that your user was created and looks like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;_id&quot;: ObjectId(&quot;5e3da6ba13ef1a137bbc8fe4&quot;),
  &quot;services&quot;: {
    &quot;password&quot;: {
      &quot;bcrypt&quot;: &quot;$2a$10$WwhjvbDzQpS2LrdkcgQJwODn.EE95T0b9NmMUNcHKyrDOlXEeybSq&quot;
    }
  },
  &quot;createdAt&quot;: 1581098682713,
  &quot;updatedAt&quot;: 1581098682713,
  &quot;emails&quot;: [
    {
      &quot;address&quot;: &quot;john.doe@john.com&quot;,
      &quot;verified&quot;: false
    }
  ]
}
</code></pre>



<p>What we can see is that a&nbsp;<code>createdAt</code>&nbsp;and&nbsp;<code>updatedAt</code>&nbsp;fields have been created. We also see that the password has been saved hashed in the database, we use bcrypt as a default but you can change it to argon2 via the options if you prefer.</p>



<p>Now let&#8217;s try to login with this user:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation {
  authenticate(
    serviceName: &quot;password&quot;
    params: {
      user: { email: &quot;john.doe@john.com&quot; }
      password: &quot;superSecurePassword&quot;
    }
  ) {
    sessionId
    tokens {
      accessToken
      refreshToken
    }
  }
}</code></pre>



<p>You should see in the playground that a new session has been created. The session is represented by:</p>



<ul class="wp-block-list"><li>a sessionId (you can check the session in the database)</li><li>a short lived JWT accessToken used to authenticate the user</li><li>a long lived refreshToken that can be used to get a new accessToken once it&#8217;s expired</li></ul>



<p>Save the access token, we will need it to authenticate our requests in the next part.</p>



<h3 class="wp-block-heading"><a href="#protecting-our-query" aria-hidden="true" class="aal_anchor" id="protecting-our-query"><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>Protecting our query</h3>



<p>Our first user has been created and we are now able to login via the API. Next step is to protect our&nbsp;<code>sensitiveInformation</code>&nbsp;query so only the authenticated users can access it.</p>



<p>accounts-js provide an&nbsp;<code>@auth</code>&nbsp;directive that we can use to protect our private queries.</p>



<p>Let&#8217;s add the directive to the query in our schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const typeDefs = gql`
  type Query {
    # We add the @auth directive
    sensitiveInformation: String @auth
  }
`;</code></pre>



<p>If you try this query, you should get an&nbsp;<code>Unauthorized</code>&nbsp;error 🛑. We can&#8217;t access this resource because we are not authenticated. To authenticate our request with the server we need to add the access token saved previously as a header of the request. The header key should be&nbsp;<code>authorization</code>&nbsp;and the value should be prefixed with&nbsp;<code>Bearer</code>. eg:&nbsp;<code>{ &quot;authorization&quot;: &quot;Bearer my-access-token&quot; }</code></p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="630" src="https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-1024x630.png" alt="" class="wp-image-2170" srcset="https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-1024x630.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-300x185.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-768x472.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-1200x738.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08.png 1281w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>You made your first authenticated query, how cool is that?</p>



<p>Well, that&#8217;s it, you are done, you now have a Graphql server that can register and authenticate new users. Pretty simple right? Next step for you is to explore the playground and play with the different queries and mutations available (verify the email, change the password etc..) :).</p>



<p>You can find the source here&nbsp;<a href="https://github.com/pradel/accounts-js-server-tutorial">https://github.com/pradel/accounts-js-server-tutorial</a>.</p>



<p>If you want to learn more about accounts-js head over our website and check the documentation <a href="https://www.accountsjs.com/">https://www.accountsjs.com/</a> 🔐.</p>


Email & password authentication with accounts-js and Apollo Server

Setting Up Authentication and Authorization with Apollo Federation

A Deep Dive on Apollo Data Sources

☝️ GraphQL File Uploads with Apollo Server 2, React Hooks, TypeScript & Amazon S3 [Tutorial]

Apollo Server File Upload Best Practices

GraphQL & Caching: The Elephant in the Room


<p>What if you could access all of your organization’s data by typing a single GraphQL query, even if that data lived in separate places? Up until now, this goal has been difficult to achieve without committing to a monolithic architecture or writing fragile schema stitching code.</p>



<p>Ideally, we want to expose&nbsp;<a href="https://principledgraphql.com/integrity#1-one-graph" target="_blank" rel="noreferrer noopener">one graph</a>&nbsp;for all of our organization’s data without experiencing the pitfalls of a monolith. What if we could have the best of both worlds: a complete schema to connect all of our data with a&nbsp;<a href="https://principledgraphql.com/integrity#2-federated-implementation" target="_blank" rel="noreferrer noopener">distributed architecture</a>&nbsp;so teams can own their portion of the graph?</p>



<p>That dream is finally a reality with the launch of&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/federation/introduction/" target="_blank" rel="noreferrer noopener"><strong>Apollo Federation</strong></a>, an architecture for building a distributed graph. Best of all, it’s open source! 🚀&nbsp;<a href="https://github.com/apollographql/federation-demo" target="_blank" rel="noreferrer noopener">Try it out now</a>&nbsp;or keep reading to learn more.</p>



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



<p><a href="https://www.apollographql.com/docs/apollo-server/federation/introduction/" target="_blank" rel="noreferrer noopener">Apollo Federation</a>&nbsp;is our answer for implementing GraphQL in a microservice architecture. It’s designed to replace schema stitching and solve pain points such as coordination, separation of concerns, and brittle gateway code.</p>



<p>Federation is based on these core principles:</p>



<ul class="wp-block-list"><li><strong>Building a graph should be declarative.</strong>&nbsp;With federation, you compose a graph declaratively from within your schema instead of writing imperative schema stitching code.</li><li><strong>Code should be separated by concern, not by types.</strong>&nbsp;Often no single team controls every aspect of an important type like a User or Product, so the definition of these types should be distributed across teams and codebases, rather than centralized.</li><li><strong>The graph should be simple for clients to consume.</strong>&nbsp;Together, federated services can form a complete, product-focused graph that accurately reflects how it’s being consumed on the client.</li><li><strong>It’s just GraphQL, using only spec-compliant features of the language.</strong>&nbsp;Any language, not just JavaScript, can implement federation.</li></ul>



<p>Apollo Federation is inspired by years of conversations with teams that use GraphQL to power their most important projects. Time and time again, we’ve heard from developers that they need an efficient way to connect data across services. Let’s learn how in the next section!</p>



<h2 class="wp-block-heading" id="02b7"><a href="#core-concepts" aria-hidden="true" class="aal_anchor" id="core-concepts"><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>Core concepts</h2>



<p>Connecting data between multiple services is where federation truly shines. The two essential techniques for connecting data are type references and type extensions. A type that can be connected to a different service in the graph is called an&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/federation/core-concepts/#entities-and-keys" target="_blank" rel="noreferrer noopener"><strong>entity</strong></a>, and we specify directives on it to indicate how both services should connect.</p>



<h3 class="wp-block-heading" id="00ed"><a href="#type-references" aria-hidden="true" class="aal_anchor" id="type-references"><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 href="https://www.apollographql.com/docs/apollo-server/federation/core-concepts/#referencing-external-types" target="_blank" rel="noreferrer noopener">Type references</a></h3>



<p>With Apollo Federation, we can declaratively reference types that live in different schemas. Let’s look at an example where we have two separate services for accounts and reviews. We want to create a&nbsp;<code>User</code>&nbsp;type that is referenced by both services.</p>



<p>In the accounts service, we use the&nbsp;<code>@key</code>&nbsp;directive to convert the&nbsp;<code>User</code>&nbsp;type to an entity. With only one line of code, we’ve indicated that the&nbsp;<code>User</code>&nbsp;type can be connected from other services in the graph through its&nbsp;<code>id</code>&nbsp;field.</p>



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



<p>In the reviews service, we can return the&nbsp;<code>User</code>&nbsp;type even though it’s defined in a different service. Thanks to type references, we can seamlessly connect the accounts and reviews service in one complete graph.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Review {
  author: User
}</code></pre>



<p>On the client, you can query the data as if both types were defined in the same schema. You no longer have to create extra field names like&nbsp;<code>authorId</code>&nbsp;or make separate round trips to a different service.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetReviews {
  reviews {
    author {
      username
    }
  }
}</code></pre>



<h3 class="wp-block-heading" id="a76b"><a href="#type-extensions" aria-hidden="true" class="aal_anchor" id="type-extensions"><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 href="https://www.apollographql.com/docs/apollo-server/federation/core-concepts/#extending-external-types" target="_blank" rel="noreferrer noopener">Type extensions</a></h3>



<p>To enable organizing services by concern, a service can&nbsp;<code>extend</code>&nbsp;a type defined in a different service to add new fields.</p>



<p>In the reviews service, we extend the&nbsp;<code>User</code>&nbsp;entity from the accounts service. First, we use the&nbsp;<code>@key</code>&nbsp;directive to specify that these two services should connect together on the&nbsp;<code>id</code>&nbsp;field defined in the&nbsp;<code>@external</code>&nbsp;accounts service. Then, we add the functionality for a user to fetch their reviews.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">extend type User @key(fields: &quot;id&quot;) {
  id: ID! @external
  reviews: [Review]
}</code></pre>



<p>The client only sees the final&nbsp;<code>User</code>&nbsp;type, which includes all of the fields merged together. Type extensions for Apollo Federation will feel familiar if you’ve used Apollo Client for&nbsp;<a target="_blank" rel="noreferrer noopener" href="https://blog.apollographql.com/announcing-apollo-client-2-5-c12230cabbb7">local state management</a>&nbsp;because they share the same programming model.</p>



<h3 class="wp-block-heading" id="0583"><a href="#production-ready-features" aria-hidden="true" class="aal_anchor" id="production-ready-features"><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>Production-ready features</h3>



<p>We designed Apollo Federation to be approachable to start with, yet capable of handling the most complex real-world use cases:</p>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/apollo-server/federation/advanced-features/#multiple-primary-keys" target="_blank" rel="noreferrer noopener"><strong>Multiple primary keys</strong></a><strong>:</strong>&nbsp;It’s not always practical to reference an entity with a single primary key. With Apollo Federation, we can reference types with multiple primary keys by adding several&nbsp;<code>@key</code>&nbsp;directives.</li><li><a href="https://www.apollographql.com/docs/apollo-server/federation/advanced-features/#compound-and-nested-keys" target="_blank" rel="noreferrer noopener"><strong>Compound primary keys</strong></a><strong>:&nbsp;</strong>Keys aren’t limited to a single field. Rather, they can be any valid selection set, including those with nested fields.</li><li><a href="https://www.apollographql.com/docs/apollo-server/federation/advanced-features/#using-denormalized-data" target="_blank" rel="noreferrer noopener"><strong>Shortcuts for faster data fetching</strong></a><strong>:</strong>&nbsp;In large organizations, it’s common to denormalize data across multiple services. With the&nbsp;<code>@provides</code>&nbsp;directive, services can use that denormalization to their advantage to provide shortcuts for fetching data faster.</li></ul>



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



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="602" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_x67g2gg-OCDaNVdqta0o8Q-1024x602.png" alt="" class="wp-image-583" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_x67g2gg-OCDaNVdqta0o8Q-1024x602.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x67g2gg-OCDaNVdqta0o8Q-300x176.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x67g2gg-OCDaNVdqta0o8Q-768x451.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x67g2gg-OCDaNVdqta0o8Q.png 1200w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>An example of a federated architecture</figcaption></figure>



<p>To implement Apollo Federation, you need two components:</p>



<ul class="wp-block-list"><li><strong>Federated services</strong>, which are standalone GraphQL APIs. You can connect data between them by extending types and creating references with the&nbsp;<code>@key</code>&nbsp;directive.</li><li>A&nbsp;<strong>gateway</strong>&nbsp;to compose the complete graph and execute federated queries</li></ul>



<p>Setting up federation with Apollo Server doesn’t require any manual stitching code. Once you have your services, you can spin up a gateway simply by passing them as a list:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const { ApolloGateway } = require(&quot;@apollo/gateway&quot;);

const gateway = new ApolloGateway({
  serviceList: [
    { name: &quot;accounts&quot;, url: &quot;https://pw678w138q.sse.codesandbox.io/graphql&quot; },
    { name: &quot;reviews&quot;, url: &quot;https://0yo165yq9v.sse.codesandbox.io/graphql&quot; },
    { name: &quot;products&quot;, url: &quot;https://x7jn4y20pp.sse.codesandbox.io/graphql&quot; },
    { name: &quot;inventory&quot;, url: &quot;https://o5oxqmn7j9.sse.codesandbox.io/graphql&quot; }
  ]
});</code></pre>



<p>The gateway crunches all of this into a single schema, indistinguishable from a hand-written monolith. To any client consuming a federated graph, it’s just regular GraphQL.</p>



<p>We didn’t want the gateway to be a black box where federated schemas and queries magically turn into data. To give teams full visibility into what’s happening with their composed graph, Apollo Server provides a query plan inspector out of the box:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="635" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-1024x635.png" alt="" class="wp-image-584" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-1024x635.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-300x186.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-768x476.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-1536x953.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-2048x1270.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-1200x744.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ZzLT_uIwafsgfKjnkrs1cQ-1980x1228.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>The query plan inspector</figcaption></figure>



<h2 class="wp-block-heading" id="5136"><a href="#try-apollo-federation-today-%f0%9f%9a%80" aria-hidden="true" class="aal_anchor" id="try-apollo-federation-today-%f0%9f%9a%80"><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>Try Apollo Federation today! 🚀</h2>



<p>We’re excited to open source Apollo Federation and get feedback from the community. To get started, we’ve created an&nbsp;<a href="https://github.com/apollographql/federation-demo" target="_blank" rel="noreferrer noopener">example repo</a>&nbsp;that demonstrates how to build a federated graph with four services and a gateway. If you want to play with the example in the browser,&nbsp;<a href="https://codesandbox.io/s/v368r9ml47" target="_blank" rel="noreferrer noopener">check out this CodeSandbox</a>.</p>



<p>Along with the example app, we added a new section to the Apollo Server docs about federation.&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/federation/introduction/" target="_blank" rel="noreferrer noopener">Read the docs</a>&nbsp;to get up to speed quickly and&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/federation/migrating-from-stitching/" target="_blank" rel="noreferrer noopener">migrate over from schema stitching</a>.</p>



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



<p>This release is the first chapter of distributed GraphQL. We can’t wait to hear about the many exciting ideas that stem from federation and see the amazing things you build. In the future, we’re eager to work with the GraphQL community to support new features and tools such as:</p>



<ul class="wp-block-list"><li>Additional languages (e.g. Java, Scala, Python) for federated services. If you’re a server maintainer, please read our&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/federation/federation-spec/" target="_blank" rel="noreferrer noopener">federation spec</a>&nbsp;to learn about adding support and reach out to us with any questions on&nbsp;<a href="https://spectrum.chat/apollo/apollo-federation?tab=posts" target="_blank" rel="noreferrer noopener">Spectrum</a>.</li><li>More federation-aware tooling, such as adding federation directive support to the&nbsp;<a href="https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo" target="_blank" rel="noreferrer noopener">Apollo VS Code</a>&nbsp;extension</li><li>Service extensions for passing additional metadata back to the gateway</li><li>Support for subscriptions and&nbsp;<code>@defer</code></li></ul>



<p>We’d love to hear your feedback on Apollo Federation.&nbsp;<a href="https://spectrum.chat/apollo/apollo-federation?tab=posts" target="_blank" rel="noreferrer noopener">Join the conversation on Spectrum</a>&nbsp;and let us know what you think!</p>


Apollo Federation


<p>As GraphQL usage increases in an organization, it’s important for teams to practice&nbsp;<a href="https://principledgraphql.com/agility#5-use-an-agile-approach-to-schema-development" target="_blank" rel="noreferrer noopener">agile schema development</a>&nbsp;and iteratively evolve their schema over time. One of the most common concerns we hear from teams is that they want to move fast with GraphQL, but they also want to make sure that the changes they’re making to their schema are safe to deploy to production.</p>



<p>This is why we’re excited to announce the official release of&nbsp;<strong>schema validation</strong>&nbsp;for teams on the Apollo platform! 🚀 Schema validation compares proposed schema changes against an organization’s production API traffic to ensure any changes won’t break existing clients. The schema validation workflow integrates with existing CI/CD pipelines and the GitHub pull request workflow to give teams the confidence to evolve their GraphQL API safely while maintaining a lean schema.</p>



<p>Take a look at the workflow in action:</p>



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



<h2 class="wp-block-heading" id="122b"><a href="#schema-validation-workflow" aria-hidden="true" class="aal_anchor" id="schema-validation-workflow"><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 validation workflow</h2>



<p>Schema validation with the Apollo platform has three components: the&nbsp;<strong>CLI</strong>&nbsp;command, the change summary&nbsp;<strong>UI</strong>, and the&nbsp;<strong>GitHub status</strong>&nbsp;integration. Together, they create a cohesive workflow that ensures any schema changes your team makes are compatible with existing clients.</p>



<h3 class="wp-block-heading" id="76c0"><a href="#cli" aria-hidden="true" class="aal_anchor" id="cli"><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>CLI</h3>



<p>Schema validation starts with a CLI command that runs during continuous integration (CI) or continuous deployment (CD). We recommend adding the&nbsp;<code>apollo service:check</code>&nbsp;command to your team’s CI/CD configuration to run on every commit or before every deploy. When&nbsp;<code>apollo service:check</code>&nbsp;runs, it outputs a summary of schema changes and a non-zero error code if there are breaking changes, isolating the important information from the noise of a source code diff.</p>



<p>Teams often have many different deployments (for example, staging vs. production) that should be independently validated.&nbsp;<code>apollo service:check</code>&nbsp;accepts a tag configuration that specifies the target environment. A common pattern, which we use internally to build the Apollo platform, is to run validation against multiple environments in parallel.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="761" height="248" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Rc_FahLy-rMskkgcsefyzg.png" alt="" class="wp-image-588" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Rc_FahLy-rMskkgcsefyzg.png 761w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Rc_FahLy-rMskkgcsefyzg-300x98.png 300w" sizes="auto, (max-width: 761px) 100vw, 761px" /><figcaption>Output from running the CLI command</figcaption></figure>



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



<p>Every&nbsp;<code>apollo service:check</code>&nbsp;execution generates a unique page in Apollo Engine that displays a list of all schema changes. When a change breaks an existing operation, the UI separates these changes out with a summary detailing which clients are affected. The breaking change is compared against the affected client’s production traffic in order to determine the impact of the change and facilitate communication between team members who own different aspects of the system.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="593" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-1024x593.png" alt="" class="wp-image-589" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-1024x593.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-300x174.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-768x445.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-1536x890.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-2048x1186.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-1200x695.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_WlV4LkVRG-HD7pl4yT2mCQ-1-1980x1147.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Schema validation UI</figcaption></figure>



<h3 class="wp-block-heading" id="6639"><a href="#github-status" aria-hidden="true" class="aal_anchor" id="github-status"><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>GitHub status</h3>



<p>Schema validation seamlessly integrates with your team’s existing GitHub workflow to display the results of the check and a link to the change summary UI right inside a Pull Request. When the status fails, indicating dangerous code, the merge can be delayed until it passes additional scrutiny. The following screenshot could be acceptable, for example a type rename that requires clients to regenerate types and mocks, while maintaining the same fields.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="777" height="388" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_bQ47wCBS5bWwaPrpFRfJyA.png" alt="" class="wp-image-590" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_bQ47wCBS5bWwaPrpFRfJyA.png 777w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_bQ47wCBS5bWwaPrpFRfJyA-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_bQ47wCBS5bWwaPrpFRfJyA-768x384.png 768w" sizes="auto, (max-width: 777px) 100vw, 777px" /><figcaption>GitHub status checks</figcaption></figure>



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



<p>We’ve been using schema validation internally at Apollo for a while now, and we’ve been impressed with the productivity boost it has given our teams. Testing every change against live production traffic ensures that we can maintain a lean schema without breaking existing clients. When breaking changes are proposed, schema validation surfaces the impact and fosters conversations so teams can proactively agree on a solution.</p>



<p>Schema validation is available for users on a paid Apollo platform plan. To try it out,&nbsp;<a href="https://engine.apollographql.com/?overlay=UpgradePlan" target="_blank" rel="noreferrer noopener">start a free Teams trial</a>&nbsp;and follow the&nbsp;<a href="https://www.apollographql.com/docs/platform/schema-validation#setup" target="_blank" rel="noreferrer noopener">setup instructions</a>. If you’d like to learn more about the Apollo platform, please contact our sales team at&nbsp;<a href="mailto:sales@apollographql.com" target="_blank" rel="noreferrer noopener">sales@apollographql.com</a>.</p>


Move fast (without breaking things)

Deploy a fullstack Apollo app with Netlify

Layering GraphQL on top of REST

Announcing Apollo Server 2


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Update: May 2022</strong><br>For our recommendation on how to handle file uploads, read <a href="https://www.apollographql.com/blog/apollo-server-file-upload-best-practices-1e7f24cdc050">Apollo Server File Uploads Best Practices</a>.</p><p>Our current recommendation is to <strong>not</strong> use the multipart request approach described in this package. In fact, this feature was removed from Apollo Server in version 3, although you can still manually integrate with the <code>graphql-upload</code> package if you take care to <a href="https://www.apollographql.com/docs/apollo-server/security/cors/#preventing-cross-site-request-forgery-csrf">protect yourself from Cross-Site Request Forgery (CSRF) attacks</a>.</p></blockquote>



<p>In web applications, one of the most common requirements is file uploads. For a while now, the question being asked around the GraphQL community is&nbsp;<strong>“How does one perform file uploads in GraphQL itself?”&nbsp;</strong>The community turned to the GraphQL specification and reference implementation but found no answers because the specification has no provisions for file uploads.</p>



<p>There are several ways you could upload files when using a GraphQL API, for example sending the file to Cloudinary or S3 directly and passing the returned URL through a GraphQL mutation. However, coordinating these multiple requests might be hard to manage. One of the simplest ways of achieving file uploads in a single request is to base64-encode a file and send as a string variable in a mutation. Another option is to send file(s) in the same request as your mutation, which I’ll cover in this post!</p>



<p><a href="https://medium.com/u/5bd1b4d20a6d?source=post_page-----5db2f3f60675----------------------" target="_blank" rel="noreferrer noopener">Jayden Seric</a>, a JavaScript engineer and GraphQL community member came up with a&nbsp;<a href="https://github.com/jaydenseric/graphql-multipart-request-spec" target="_blank" rel="noreferrer noopener">specification for GraphQL multipart form requests(file uploads)</a>&nbsp;and also provided a reference implementation.</p>



<p>At Apollo, we are committed to making sure you have the best developer experience throughout your GraphQL journey.</p>



<p>We decided to incorporate the much requested file uploads feature into&nbsp;<strong>Apollo Server 2.0</strong>, thanks to inspiration from the wonderful&nbsp;<a href="https://github.com/jaydenseric/apollo-upload-server" target="_blank" rel="noreferrer noopener">apollo-upload-server</a>&nbsp;package by Jayden. With GraphQL, we are achieving a single paradigm of data management. Just how Apollo Client merges remote and local data. Apollo Server enables you to combine multiple previously orthogonal data sources into a single paradigm. This post being about the specific case of file uploads and JSON data.</p>



<h2 class="wp-block-heading" id="312e"><a href="#how-it-works" aria-hidden="true" class="aal_anchor" id="how-it-works"><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>How it works</h2>



<p>The upload functionality follows the GraphQL multipart form requests specification. Two parts are needed to make the upload work correctly. The server and the client:</p>



<p><strong>The Client:&nbsp;</strong>On the client, file objects are mapped into a mutation and sent to the server in a multipart request.</p>



<p><strong>The Server:&nbsp;</strong>The multipart request is received. The server processes it and provides an upload argument to a resolver. In the resolver function, the upload promise resolves an object.</p>



<p>Stay with me! The resolver section will reveal what the object contains and how you can use it.</p>



<h2 class="wp-block-heading" id="9bde"><a href="#server-configuration" aria-hidden="true" class="aal_anchor" id="server-configuration"><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>Server Configuration</h2>



<p>The default option for enabling file uploads in Apollo Server 2.0 involves creating a schema and using the&nbsp;<code>Upload</code>&nbsp;type like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const { ApolloServer, gql } = require(&#039;apollo-server&#039;);

const typeDefs = gql`
  type File {
    filename: String!
    mimetype: String!
    encoding: String!
  }
  type Query {
    uploads: [File]
  }
  type Mutation {
    singleUpload(file: Upload!): File!
  }
`;</code></pre>



<p>The first question you’re most likely to ask from the schema observation above is “Where does&nbsp;<code>Upload</code>&nbsp;scalar type come from?” Don’t fret. It is added automatically by Apollo Server.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Apollo Server 2.0 automatically adds the&nbsp;<code>Upload</code>&nbsp;scalar to the schema, when you are not setting the schema manually.</p></blockquote>



<h3 class="wp-block-heading" id="8103"><a href="#resolver-implementation" aria-hidden="true" class="aal_anchor" id="resolver-implementation"><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>Resolver implementation</h3>



<p>Earlier on, I mentioned that the server returns an upload promise that resolves an object. The object contains the following:</p>



<ol class="wp-block-list"><li><em>stream:</em>&nbsp;The upload stream manages&nbsp;<a rel="noreferrer noopener" href="https://nodejs.org/api/stream.html" target="_blank">streaming the file(s)</a>&nbsp;to a filesystem or any storage location of your choice. e.g. S3, Azure, Cloudinary, e.t.c.</li><li><em>filename:</em>&nbsp;The name of the uploaded file(s).</li><li><em>mimetype:&nbsp;</em>The MIME type of the file(s) such as&nbsp;<code>text/plain</code>,&nbsp;<code>application/octet-stream</code>, etc.</li><li><em>encoding:&nbsp;</em>The file encoding such as UTF-8.</li></ol>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    files: () =&gt; {
      // Return the record of files uploaded from your DB or API or filesystem.
    }
  },
  Mutation: {
    async singleUpload(parent, { file }) {
      const { stream, filename, mimetype, encoding } = await file;

      // 1. Validate file metadata.

      // 2. Stream file contents into cloud storage:
      // https://nodejs.org/api/stream.html

      // 3. Record the file upload in your DB.
      // const id = await recordFile( … )

      return { filename, mimetype, encoding };
    }
  },
};</code></pre>



<p>In the code above, the file can be validated after the promise resolves. If the file size or type is right (depending on the validation technique), it can be streamed into cloud storage like&nbsp;<a href="https://cloudinary.com/documentation/node_image_upload" target="_blank" rel="noreferrer noopener">Cloudinary</a>&nbsp;and the returned link can be stored in a database. Otherwise an&nbsp;<a href="https://dev-blog.apollodata.com/full-stack-error-handling-with-graphql-apollo-5c12da407210" target="_blank" rel="noreferrer noopener">Apollo error can be thrown</a>&nbsp;within the resolver.</p>



<h2 class="wp-block-heading" id="615d"><a href="#client-setup" aria-hidden="true" class="aal_anchor" id="client-setup"><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>Client Setup</h2>



<p>If the user is expected to upload files from an interactive client UI, then you need to install the&nbsp;<code>apollo-upload-client</code>&nbsp;package from npm. And deal with single and multiple files from the client.</p>



<p><em>Single file upload example from the client:</em></p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import gql from &#039;graphql-tag&#039;
import { Mutation } from &#039;react-apollo&#039;

export const UPLOAD_FILE = gql`
  mutation uploadFile($file: Upload!) {
    uploadFile(file: $file) {
      filename
    }
  }
`;

const uploadOneFile = () =&gt; {
  return (   
    &lt;Mutation mutation={UPLOAD_FILE}&gt;
      {uploadFile =&gt; (
        &lt;input
        type=&quot;file&quot;
        required
        onChange={({ target: { validity, files: [file] } }) =&gt;
          validity.valid &amp;&amp; uploadFile({ variables: { file } });
        }
       /&gt;
      )}
    &lt;/Mutation&gt;
  );
};</code></pre>



<p>Use&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/FileList&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;FileList&lt;/a&gt;</code>,&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/File&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;File&lt;/a&gt;</code>,&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/Blob&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;Blob&lt;/a&gt;</code>&nbsp;or&nbsp;<code>&lt;a href=&quot;https://github.com/jaydenseric/apollo-upload-client#react-native&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;ReactNativeFile&lt;/a&gt;</code>&nbsp;instances anywhere within query or mutation input variables to send a&nbsp;<a href="https://github.com/jaydenseric/graphql-multipart-request-spec" target="_blank" rel="noreferrer noopener">GraphQL multipart request</a>. In the example above, we operated a single file upload, thus using&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/File&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;File&lt;/a&gt;</code><code>.</code></p>



<p>The user selects a file, the client validates the file and immediately sends a multipart request in the same request as the&nbsp;<code>uploadFile</code>&nbsp;mutation to the server.</p>



<p>Check out the&nbsp;<a href="https://www.apollographql.com/docs/guides/file-uploads.html" target="_blank" rel="noreferrer noopener">file uploads documentation for more information on multiple and blob file uploads from the client.</a></p>



<h2 class="wp-block-heading" id="9a10"><a href="#try-it-out" aria-hidden="true" class="aal_anchor" id="try-it-out"><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>Try it out</h2>



<p>A&nbsp;<a href="https://github.com/jaydenseric/apollo-upload-examples" target="_blank" rel="noreferrer noopener">full-stack working example created by Jayden is available on GitHub</a>. Clone and try it out. Feel free to provide feedback.</p>



<p>To keep learning, check out our<a href="https://www.apollographql.com/docs/" target="_blank" rel="noreferrer noopener">&nbsp;new best practices guides about topics like schema design, versioning, access control, and more.</a></p>



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



<p>Finally, I hope you’ll also&nbsp;<a href="https://summit.graphql.com/" target="_blank" rel="noreferrer noopener">join us at the 3rd annual GraphQL Summit on Nov 7–8 in San Francisco</a>. With over 800 attendees expected, it’s the largest GraphQL developer event in the world. Super early bird tickets are selling fast, so&nbsp;<a href="https://www.eventbrite.com/e/graphql-summit-2018-tickets-46601841362" target="_blank" rel="noreferrer noopener">register today</a>&nbsp;to reserve your spot!</p>


File Uploads with Apollo Server 2.0


<p>A common challenge that developers experience as they build products is how quickly their apps grow in complexity. For GraphQL services, your request sizes and query strings fatten over time, which in turn leads to extra weight transferred over the network. We solved this challenge by shipping&nbsp;<strong>Automatic Persisted Queries</strong>&nbsp;— a tool to that improves GraphQL network performance by reducing request size.</p>



<p>In Apollo Server 1.x, Automatic Persisted Queries and CDN caching depended on a closed-source Go component called the “Engine Proxy”. But with&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/whats-new.html" target="_blank" rel="noreferrer noopener">Apollo Server 2.0</a>, our goal is that it’s the only tool you need to implement a production-ready GraphQL API. So how could we take care of this issue?</p>



<p>As part of Apollo Server 2.0, we’re open sourcing all of the features of the Engine proxy!</p>



<p>Apollo Server 2.0 now has Automatic Persisted Queries (APQ) and CDN caching built right in, to greatly enhance your network performance. In the rest of the post, I’ll show you how to use them.</p>



<p>Performance will be a first-class citizen in your GraphQL services with Automatic Persisted Queries and CDN caching.</p>



<h2 class="wp-block-heading" id="a87a"><a href="#the-cost-of-graphql-queries" aria-hidden="true" class="aal_anchor" id="the-cost-of-graphql-queries"><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 cost of GraphQL queries</h2>



<p>The size of individual queries in your app can be a bottleneck for smooth performance. The larger the queries, the more time it takes to send them over the network.</p>



<p>We’ve seen GraphQL query sizes in production ranging well above 10 KB,&nbsp;<em>just for the query text</em>. This is can be a significant overhead when compared with a simple REST URL of 50–100 characters. When paired with the fact that the uplink speed from the client is typically the most bandwidth-constrained part of the chain, large queries can become bottlenecks for client performance.</p>



<p>The slower a user’s connection is, the more costly those extra bytes become, and the longer it takes for the client to transmit its request. This is exactly what&nbsp;<strong>Automatic Persisted Queries</strong>&nbsp;solves.</p>



<h2 class="wp-block-heading" id="2c49"><a href="#what-are-automatic-persisted-queries" aria-hidden="true" class="aal_anchor" id="what-are-automatic-persisted-queries"><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 are Automatic Persisted Queries?</h2>



<p>With&nbsp;<strong>Automatic Persisted Queries</strong>, the client has the ability to ask the server if it needs the full query by sharing a small, 64-byte hashed representation of it, and only sending the full query if the server hasn’t seen that request before.</p>



<h3 class="wp-block-heading" id="a031"><a href="#how-it-works" aria-hidden="true" class="aal_anchor" id="how-it-works"><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>How it works</h3>



<p>Apollo Server checks if a request coming from the client contains a persisted query hash. If a hash is detected, Apollo Server looks up its registry for the corresponding query. Upon finding a match, Apollo Server expands the request with the full text of the query and executes it.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="714" height="422" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_mMsPHtd3-9P7DQcB5B1d7g.png" alt="" class="wp-image-717" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_mMsPHtd3-9P7DQcB5B1d7g.png 714w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mMsPHtd3-9P7DQcB5B1d7g-300x177.png 300w" sizes="auto, (max-width: 714px) 100vw, 714px" /><figcaption>Optimal Performance Path</figcaption></figure>



<p>On the other hand, if no query is found for a hash, the server will notify the client to resend the request with the full query so that it can store the query / hash mapping in the registry for subsequent requests to profit from.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="730" height="502" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_1QC1Q6atKn1k7X8ZDUC9jA.png" alt="" class="wp-image-716" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_1QC1Q6atKn1k7X8ZDUC9jA.png 730w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_1QC1Q6atKn1k7X8ZDUC9jA-300x206.png 300w" sizes="auto, (max-width: 730px) 100vw, 730px" /><figcaption>New Performance Path</figcaption></figure>



<h3 class="wp-block-heading" id="1501"><a href="#how-to-configure-the-cache-store" aria-hidden="true" class="aal_anchor" id="how-to-configure-the-cache-store"><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>How to configure the cache store</h3>



<p>By default, Apollo Server is configured to use an in-memory cache to store the query hashes. While this works great for many projects, highly-trafficked deployments or deployments where the processes are short-lived (like Amazon Lambda or Google Cloud Functions) will benefit from using a shared cache store, such as Memcached or Redis. These stores can be configured via the Apollo Server constructor:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const { MemcachedCache } = require(&#039;apollo-server-memcached&#039;);
const { ApolloServe } = require(&#039;apollo-server&#039;);

const server = new ApolloServer({
  ...
  persistedQueries: {
    cache: new MemcachedCache(
      [&#039;memcached-server-1&#039;, &#039;memcached-server-2&#039;, &#039;memcached-server-3&#039;],
      { retries: 10, retry: 10000 }, // Options
    ),
  },
});</code></pre>



<h3 class="wp-block-heading" id="a967"><a href="#client-setup" aria-hidden="true" class="aal_anchor" id="client-setup"><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>Client Setup</h3>



<p>Finally, you need to turn on APQ in your client to start sending hashes. You can set it up in your client app with Apollo Link, like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { createPersistedQueryLink } from &quot;apollo-link-persisted-queries&quot;;
import { createHttpLink } from &quot;apollo-link-http&quot;;
import { InMemoryCache } from &quot;apollo-cache-inmemory&quot;;
import ApolloClient from &quot;apollo-client&quot;;

const link = createPersistedQueryLink().concat(createHttpLink({ uri: &quot;/graphql&quot; }));

const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: link,
});</code></pre>



<p>Ready to give it a try? Check out&nbsp;<a href="https://www.apollographql.com/docs/guides/performance.html#automatic-persisted-queries" target="_blank" rel="noreferrer noopener">the documentation here</a>&nbsp;to get your app set up and running with Automatic Persisted Queries.</p>



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



<p>Another important optimization that can be really helpful for commonly-executed queries is CDN caching. Placing your server behind a CDN allows you to deliver data faster to the clients your users interact with.</p>



<p>Most GraphQL requests are large POST requests. Therefore, improving network performance with CDN integration will involve you following these steps:</p>



<ol class="wp-block-list"><li><a rel="noreferrer noopener" href="https://www.apollographql.com/docs/guides/performance.html#setup-cdn" target="_blank">Set up a CDN and configure it to send requests to Apollo Server.</a></li><li><a rel="noreferrer noopener" href="https://www.apollographql.com/docs/guides/performance.html#cache-hints" target="_blank">Add cache hints to your schema so that Apollo Server knows which fields and types are cacheable and for how long.</a></li></ol>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Dog @cacheControl(maxAge: 120) {
  id: String!
  breed: String!
  displayImage: String @cacheControl(maxAge: 240)
  images: [Image]
  subbreeds: [String]
}</code></pre>



<p>For example, the schema above indicates that all fields that return a&nbsp;<code>Dog</code>&nbsp;type should be cached for 120 seconds, and that the&nbsp;<code>displayImage</code>&nbsp;field itself should be cached for 240 seconds.</p>



<p><a href="https://www.apollographql.com/docs/guides/performance.html#enable-apq" target="_blank" rel="noreferrer noopener">3. Finally, enable automatic persisted queries.</a></p>



<p>Apollo Server makes it straightforward to use CDNs with GraphQL queries to cache full responses while still executing more dynamic queries as usual.</p>



<h2 class="wp-block-heading" id="1b2e"><a href="#one-more-thing" aria-hidden="true" class="aal_anchor" id="one-more-thing"><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 More thing!</h2>



<p>Over the past few months, we’ve worked very hard in making Apollo Server 2.0 your go-to API server in your GraphQL toolbox. And to help you get over your fear of missing out, we’re&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/whats-new.html" target="_blank" rel="noreferrer noopener">constantly updating the docs</a>&nbsp;to give you a healthy pathway in learning to consume&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/" target="_blank" rel="noreferrer noopener">Data Sources, File uploads, metrics handling, subscriptions and a plethora of features.</a></p>



<p>Furthermore, feel free to check out our<a href="https://www.apollographql.com/docs/" target="_blank" rel="noreferrer noopener">&nbsp;new best practices guides about topics like schema design, versioning, access control, and more.</a></p>



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



<p>Finally, I hope you’ll also&nbsp;<a href="https://summit.graphql.com/" target="_blank" rel="noreferrer noopener">join us at the 3rd annual GraphQL Summit on Nov 7–8 in San Francisco</a>. With over 800 attendees expected, it’s the largest GraphQL developer event in the world. Super early bird tickets are selling fast, so&nbsp;<a href="https://www.eventbrite.com/e/graphql-summit-2018-tickets-46601841362" target="_blank" rel="noreferrer noopener">register today</a>&nbsp;to reserve your spot!</p>


Automatic Persisted Queries and CDN caching with Apollo Server 2.0


<p>Over the last few weeks, you might have heard a lot about&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/whats-new.html" target="_blank" rel="noreferrer noopener">Apollo Server 2.0</a>, which is currently in the RC stage with the final release coming soon. It’s the biggest open source release we’ve worked on since Apollo Client 2.0 last year. Here’s our focus for this major new version:</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Apollo Server 2 will come with everything you need to take your GraphQL API from prototype to production.</p></blockquote>



<p>No more pulling in several libraries, wiring them together, and figuring out best practices on your own. We heard it loud and clear from the community: you should just be able to install one open source tool for GraphQL API development and use it throughout your whole development lifecycle.</p>



<p>We’ve also heard from our customers that the features provided by&nbsp;<a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;around performance tracing, error tracking, CDN integration, caching, and more are critical to their production success. Historically, those features have relied on a closed-source component implemented in Go that we called the “Engine Proxy”. This was in conflict with our goal above — that Apollo Server should be the only tool you need. So how did we solve this problem? We picked the most straightforward option:</p>



<p><strong>Apollo Server 2.0 will contain all of the features of the Engine Proxy, reimplemented with 100% open-source JavaScript.</strong></p>



<p>This took a lot of work over the past few months, but it means you will be able to run all of the features of Engine anywhere you can run JavaScript. You don’t need to install a separate package anymore, although you can still use the standalone proxy component with non-JavaScript servers.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="539" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_TMnqhxJutKJ_VihGJ8XVrw-1024x539.png" alt="" class="wp-image-722" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_TMnqhxJutKJ_VihGJ8XVrw-1024x539.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TMnqhxJutKJ_VihGJ8XVrw-300x158.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TMnqhxJutKJ_VihGJ8XVrw-768x404.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TMnqhxJutKJ_VihGJ8XVrw-1200x631.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TMnqhxJutKJ_VihGJ8XVrw.png 1494w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Features like&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/features/apq.html" target="_blank" rel="noreferrer noopener">Automatic Persisted Queries</a>&nbsp;and&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/features/cdn.html" target="_blank" rel="noreferrer noopener">CDN integration</a>&nbsp;now work out of the box, and we’ll talk more about how to use them soon.</p>



<p>Today, we’re going to focus on cloud-based features like performance tracing and error tracking, which you can now set up just by providing an API key. Let’s take a look!</p>



<p><em>Learn more about Apollo Server 2.0 in&nbsp;</em><a href="https://www.apollographql.com/docs/apollo-server/v2/" target="_blank" rel="noreferrer noopener"><em>the new docs</em></a><em>.</em></p>



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



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



<p>Because all of the machinery to collect and report resolver performance data and errors is built right into Apollo Server 2, setting everything up is now extremely simple:</p>



<ol class="wp-block-list"><li>Get an API key by&nbsp;<a href="https://engine.apollographql.com/" target="_blank" rel="noreferrer noopener">signing into Engine</a>&nbsp;and creating a service.</li><li>Pass the API key in an&nbsp;<code>ENGINE_API_KEY</code>&nbsp;environment variable.</li></ol>



<p>That’s all!</p>



<h3 class="wp-block-heading" id="c324"><a href="#try-it-yourself" aria-hidden="true" class="aal_anchor" id="try-it-yourself"><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>Try it yourself</h3>



<p>If you want to see how easy it can be, let’s go through running a simple example to see data show up in Engine.</p>



<p>First, go download the Apollo Server 2.0 Pupstagram example app from here:&nbsp;<a href="https://github.com/apollographql/pupstagram-api" target="_blank" rel="noreferrer noopener">https://github.com/apollographql/pupstagram-api</a></p>



<p>Then, log into Engine and create a service to get an API key:&nbsp;<a href="https://engine.apollographql.com/" target="_blank" rel="noreferrer noopener">https://engine.apollographql.com</a></p>



<p>Then, run it with the key passed as an environment variable:</p>



<pre class="wp-block-preformatted">ENGINE_API_KEY=&lt;key here&gt; npm start</pre>



<h3 class="wp-block-heading" id="edfe"><a href="#running-queries-to-see-traces" aria-hidden="true" class="aal_anchor" id="running-queries-to-see-traces"><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>Running queries to see traces</h3>



<p>Open the GraphQL Playground, and run the query below a few times:</p>



<pre class="wp-block-preformatted">query GetCorgiImage {<br>  dog(breed: "corgi") {<br>    displayImage<br>    subbreeds<br>  }<br>}</pre>



<p>In the sidebar of the Engine UI, click on the&nbsp;<code>GetCorgiImage</code>&nbsp;operation that should show up. Click on the “Traces” tab. Now you can see the per-request traces in Engine:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="282" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg-1024x282.png" alt="" class="wp-image-721" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg-1024x282.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg-300x83.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg-768x212.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg-1536x424.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg-1200x331.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_56zftV9VYbrevHwKlu9SRg.png 1856w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Now, run the query a few dozen times to get several samples of data. In the “Performance” tab, you’ll can also see the data aggregated over time:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="350" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg-1024x350.png" alt="" class="wp-image-720" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg-1024x350.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg-300x102.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg-768x262.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg-1536x524.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg-1200x410.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KInLXod-_L9xV9d2kKvjwg.png 1922w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Congratulations! Engine is all set up and ready to go, and you didn’t have to do anything except pass the API key with an environment variable!</p>



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



<p>When you deploy to production, don’t forget to set the environment variable. You can host your Apollo Server app anywhere you like! You can also set up separate services in Engine for production vs. development, so that you can avoid mixing up data from different environments.</p>



<h2 class="wp-block-heading" id="4ac0"><a href="#run-everywhere-get-performance-and-error-insights" aria-hidden="true" class="aal_anchor" id="run-everywhere-get-performance-and-error-insights"><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>Run everywhere, get performance and error insights</h2>



<p>There’s one more focus area for Apollo Server 2.0 that we haven’t talked about that much yet: You should be able to run your GraphQL API anywhere JavaScript runs. And that’s a lot of places:</p>



<ol class="wp-block-list"><li>Container-based hosting providers, like&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/deployment/heroku.html" target="_blank" rel="noreferrer noopener">Heroku</a>&nbsp;and Zeit Now.</li><li>Serverless environments, like&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/deployment/lambda.html" target="_blank" rel="noreferrer noopener">AWS Lambda</a>, Google Cloud Functions, and Azure Functions.</li><li>Edge environments, like Cloudflare Workers and Fly.io.</li></ol>



<p>You heard me right — with Apollo Server 2.0, you’ll be able to deploy your GraphQL API to 150+ edge locations, responding to your users’ GraphQL requests with lower latency than ever before. Learn more in <a rel="noreferrer noopener" href="https://medium.com/u/f88cf847c7fc?source=post_page-----baa6158f3c09----------------------" target="_blank">Matt</a>’s opening keynote from Apollo Day:</p>



<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="Apollo Day SF 2018 - Opening Keynote (Matt DeBergalis)" width="580" height="326" src="https://www.youtube.com/embed/T1yLneMFabg?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



<p>This is another important implication of moving the performance and error tracking that used to be in the Go-based Engine Proxy to JavaScript inside Apollo Server. Now, you can get the production insights from Engine even when you’re running in a serverless environment like Lambda or an edge environment like a Cloudflare worker.</p>



<p>If running GraphQL on the edge is exciting to you, we’ve set up a form where you can sign up to get news about this concept and become an early tester. Check it out at:&nbsp;<a href="https://www.apollographql.com/edge" target="_blank" rel="noreferrer noopener">https://www.apollographql.com/edge</a></p>



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



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



<p>I’m really excited that Apollo Server 2.0 is going to make lots of aspects of GraphQL API development a lot easier, and make it simpler for product developers to stand up a GraphQL layer over their existing backends.</p>



<p>We still often hear that while it’s super exciting on the frontend, adding a new type of API feels like a daunting task, and we’re dedicated to breaking down that barrier. Read more about what we’re doing in Apollo Server 2.0 to make that possible:</p>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/apollo-server/v2/getting-started.html" target="_blank" rel="noreferrer noopener">The new Apollo Server 2.0 getting started guide in the docs</a>.</li><li><a href="https://dev-blog.apollodata.com/easy-and-performant-graphql-over-rest-e02796993b2b" target="_blank" rel="noreferrer noopener">Data Sources, the new simple way to call REST APIs from GraphQL</a>.</li><li><a href="https://www.apollographql.com/docs/" target="_blank" rel="noreferrer noopener">New best practices guides about topics like schema design, versioning, access control, and more</a>.</li></ul>



<p>And more coming up soon! We’re just putting the finishing touches on the release, but we’re already using the RC in our own production apps. Join us and send any feedback you have on GitHub!</p>



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



<p>I hope you’ll also&nbsp;<a href="https://summit.graphql.com/" target="_blank" rel="noreferrer noopener">join us at the 3rd annual GraphQL Summit on Nov 7–8 in San Francisco</a>. With over 800 attendees expected, it’s the largest GraphQL developer event in the world. Super early bird tickets are selling fast, so&nbsp;<a href="https://www.eventbrite.com/e/graphql-summit-2018-tickets-46601841362" target="_blank" rel="noreferrer noopener">register today</a>&nbsp;to reserve your spot!<br></p>


Apollo Server 2.0: Performance and error reporting built in


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Last Friday, we published a first release candidate of&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/whats-new.html" target="_blank" rel="noreferrer noopener">Apollo Server 2.0</a>, a 100% open source JavaScript GraphQL server that bakes in the best practices we’ve learned working with hundreds of teams running GraphQL in production. This post introduces data sources, one of its new features.</p></blockquote>



<p>In our experience, the right way to deploy GraphQL is as a layer between your apps and your existing APIs and services. This approach lets teams leverage and complement the investments they’ve made in microservices and infrastructure, and provides product engineers a straightforward, low-friction path to rolling out GraphQL.</p>



<p>That makes patterns for loading data from REST APIs especially important, so we’ve made a built-in answer to that a key part of Apollo Server 2.0. That’s data sources — a new pattern for fetching and caching data from REST endpoints that replaces DataLoader.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="683" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-1024x683.jpg" alt="" class="wp-image-736" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-1024x683.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-300x200.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-768x512.jpg 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-1536x1024.jpg 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-2048x1365.jpg 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-1200x800.jpg 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_CKtkiJwA-k8QhmcQOyiqGg-1980x1320.jpg 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Fetching &amp; Caching Data from REST endpoints</figcaption></figure>



<h2 class="wp-block-heading" id="ef7e"><a href="#data-sources-a-best-pattern-for-fetching-from-rest-apis" aria-hidden="true" class="aal_anchor" id="data-sources-a-best-pattern-for-fetching-from-rest-apis"><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 sources — a best pattern for fetching from REST APIs</h2>



<p>Data sources are classes that encapsulate fetching data from a particular service, with built-in support for caching, deduplication, and error handling. You write the code that is specific to interacting with your backend, and Apollo Server takes care of the rest.</p>



<p>It’s easy to get started. All you need to do to define a data source is to extend the&nbsp;<code>RESTDataSource</code>&nbsp;class and implement the data fetching methods that your resolvers require. Your implementation of these methods can call on convenience methods built into the<code>RESTDataSource</code>&nbsp;class to perform HTTP requests, while making it easy to build up query parameters, parse JSON results, and handle errors.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">class MoviesAPI extends RESTDataSource {
  baseURL = &#039;https://movies-api.example.com&#039;;

  async getMovie(id: string) {
    return this.get(`movies/${id}`);
  }

  async getMostViewedMovies(limit: number = 10) {
    const data = await this.get(&#039;movies&#039;, {
      per_page: limit,
      order_by: &#039;most_viewed&#039;,
    });
    return data.results;
  }
}</code></pre>



<p>Data sources allow you to intercept fetches to set headers or make other changes to the outgoing request. This is most often used for authorization. Data sources also get access to the GraphQL execution context, which is a great place to store a user token or other information you need to have available.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">class PersonalizationAPI extends RESTDataSource {
  baseURL = &#039;https://personalization-api.example.com&#039;;

  willSendRequest(request: Request) {
    request.headers.set(&#039;Authorization&#039;, this.context.token);
  }

  async getFavorites() {
    return this.get(&#039;favorites&#039;);
  }

  async getProgressFor(movieId: string) {
    return this.get(&#039;progress&#039;, {
      id: movieId,
    });
  }
}</code></pre>



<p>You pass the data sources to use as an option to the&nbsp;<code>ApolloServer</code>&nbsp;constructor:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const server = new ApolloServer({
  typeDefs,
  resolvers,
  dataSources: () =&gt; {
    return {
      moviesAPI: new MoviesAPI(),
      personalizationAPI: new PersonalizationAPI(),
    };
  },
  context: () =&gt; {
    return {
      token:
        &#039;foo&#039;,
    };
  }
});</code></pre>



<p>Apollo Server will then put the data sources on the context for every request, so you can access them from your resolvers. It will also give your data sources access to the context. (The reason for not having users put data sources on the context directly is because that would lead to a circular dependency.)</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">  Query: {
    movie: async (_source, { id }, { dataSources }) =&gt; {
      return dataSources.moviesAPI.getMovie(id);
    },
    mostViewedMovies: async (_source, _args, { dataSources }) =&gt; {
      return dataSources.moviesAPI.getMostViewedMovies();
    },
    favorites: async (_source, _args, { dataSources }) =&gt; {
      return dataSources.personalizationAPI.getFavorites();
    },
  },</code></pre>



<h2 class="wp-block-heading" id="786d"><a href="#what-about-dataloader" aria-hidden="true" class="aal_anchor" id="what-about-dataloader"><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 about DataLoader?</h2>



<p><a href="https://github.com/facebook/dataloader" target="_blank" rel="noreferrer noopener">DataLoader</a>&nbsp;was designed by Facebook with a specific use case in mind: deduplicating and batching object loads from a data store. It provides a memoization cache, which avoids loading the same object multiple times during a single GraphQL request, and it coalesces loads that occur during a single tick of the event loop into a batched request that fetches multiple objects at once.</p>



<p>Although DataLoader is great for that use case, it’s less helpful when loading data from REST APIs because its primary feature is&nbsp;<em>batching</em>, not&nbsp;<em>caching</em>. What we’ve found to be far more important when layering GraphQL over REST APIs is having a resource cache that saves data across multiple GraphQL requests, can be shared across multiple GraphQL servers, and has cache management features like expiry and invalidation that leverage standard HTTP cache control headers.</p>



<p>In fact, we’ve worked with many teams that have implemented exactly this pattern in their GraphQL server, using something like Redis or Memcached as a backing store for the resource cache. Time and again these teams have told us how critical this cache is, but also that their homegrown implementations are incomplete and hard to maintain. Data sources is our answer for that.</p>



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



<p>Resource caching is especially valuable in a GraphQL server because it unlocks&nbsp;<em>partial query caching</em>&nbsp;— a design pattern that lets the GraphQL layer cache responses from underlying APIs and then assemble them into arbitrary query results without refetching from the server.</p>



<p>While a a REST endpoint is meant to represent a single resource, GraphQL allows clients to ask for the exact data they need in one request, combining data from a variety of sources. This makes whole GraphQL responses difficult to cache efficiently because they often contain data with very different lifetimes, or a blend of publicly cacheable and user-specific data.</p>



<p>Take this example from an actual customer API. The query asks for information about a TV series, as well as a season of episodes. All this is publicly cacheable (the same for all users), and also relatively static (cacheable with a long TTL). In addition, we ask for the progress for every episode however, which is specific to the current user and also likely to change often.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">{
  series(id: &quot;98794&quot;) {
    title
    description
    season(number: 1) {
      episodes {
        id
        episodeNumber
        assetTitle
        description
        progress {
          percent
          position
        }
      }
    }
  }
}</code></pre>



<p>If we were fetching data from the underlying REST APIs directly, we would fetch and cache season and episode data separately from the progress data. But because we’re asking for all of this in a single request, the response we receive from the GraphQL layer isn’t cacheable.</p>



<p>Data sources gives you the best of both worlds. Requests made through REST data sources are automatically cached based on the caching headers returned in the response, which many REST APIs already set. This means partial results are cached, but we retain the flexibility that comes with GraphQL to select and combine data from different sources.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="445" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_3qy8uuqh2hN4NrbVcdqzSA-1024x445.png" alt="" class="wp-image-737" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_3qy8uuqh2hN4NrbVcdqzSA-1024x445.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3qy8uuqh2hN4NrbVcdqzSA-300x130.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3qy8uuqh2hN4NrbVcdqzSA-768x334.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3qy8uuqh2hN4NrbVcdqzSA-1200x522.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3qy8uuqh2hN4NrbVcdqzSA.png 1476w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>The first time the query is executed, we start out by fetching the data for the series, then the season, followed by progress data for every episode.</figcaption></figure>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="445" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_YSiKhxdvmQYNqR0igbfRlw-1024x445.png" alt="" class="wp-image-738" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_YSiKhxdvmQYNqR0igbfRlw-1024x445.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_YSiKhxdvmQYNqR0igbfRlw-300x130.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_YSiKhxdvmQYNqR0igbfRlw-768x334.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_YSiKhxdvmQYNqR0igbfRlw-1200x522.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_YSiKhxdvmQYNqR0igbfRlw.png 1476w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>As long as the cached content hasn’t expired, subsequent requests can load the series and season data from the cache, and only have to fetch progress data afresh.</figcaption></figure>



<p>By default, resource caching will use an in memory LRU cache. Apollo Server also includes support for using Memcached or Redis as shared cache backends. And soon, if you’re running on edge environments like <a href="https://www.apollographql.com/edge">Cloudflare Workers </a>or <a rel="noreferrer noopener" href="https://fly.io/" target="_blank">fly.io</a>, we’ll automatically use the cache built into those environments as well.</p>



<h2 class="wp-block-heading" id="283c"><a href="#try-it-out" aria-hidden="true" class="aal_anchor" id="try-it-out"><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>Try it out</h2>



<p>To get started, refer to the&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/features/data-sources.html" target="_blank" rel="noreferrer noopener">data sources section</a>&nbsp;in the Apollo Server 2 docs. We’re eager to hear your input and learn from your experiences. As always, please get in touch on&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">Twitter</a>&nbsp;or&nbsp;<a href="https://www.apollographql.com/slack" target="_blank" rel="noreferrer noopener">Apollo Slack</a>&nbsp;if you’d like to help.</p>



<figure class="wp-block-image size-large"><a href="https://summit.graphql.com/"><img loading="lazy" decoding="async" width="800" height="400" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_89Id4_dTlCejzzEWfA8AfA-1.png" alt="" class="wp-image-735" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_89Id4_dTlCejzzEWfA8AfA-1.png 800w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_89Id4_dTlCejzzEWfA8AfA-1-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_89Id4_dTlCejzzEWfA8AfA-1-768x384.png 768w" sizes="auto, (max-width: 800px) 100vw, 800px" /></a><figcaption>GraphQL Summit 2018 (Nov 7–8, San Francisco)</figcaption></figure>



<p>I hope you’ll also&nbsp;<a href="https://summit.graphql.com/" target="_blank" rel="noreferrer noopener">join us at the 3rd annual GraphQL Summit on Nov 7–8 in San Francisco</a>. With over 800 attendees expected, it’s the largest GraphQL developer event in the world. Super early bird tickets are selling fast, so&nbsp;<a href="https://www.eventbrite.com/e/graphql-summit-2018-tickets-46601841362" target="_blank" rel="noreferrer noopener">register today</a>&nbsp;to reserve your spot!</p>


Easy and performant GraphQL over REST


<p><em>This is a guest post by Marc-Andre Giroux, who is currently working on the ecosystem API team at GitHub. He’s been writing and thinking a lot about GraphQL continuous evolution and schema design. His book, <a rel="noreferrer noopener" href="https://productionreadygraphql.com/book/" target="_blank">Production Ready GraphQL</a>, was released in early March 2020.</em></p>



<p>While GraphQL allows us to continuously evolve our schemas, using deprecations, for example, we should not take the decision of deprecating schema members lightly. In the end, a deprecation still requires work from all your integrators in the best case and is breaking change for anyone that has not made the change in the worst case.</p>



<p>While it’s possible to make these changes in an easier way for everyone with better tooling and documentation like what we’ve&nbsp;<a href="https://developer.github.com/v4/breaking_changes/" target="_blank" rel="noreferrer noopener">built</a>&nbsp;at&nbsp;<a href="https://developer.github.com/v4/changelog/" target="_blank" rel="noreferrer noopener">GitHub</a>, we must keep in mind that using deprecations should be absolute&nbsp;<strong>last resort&nbsp;</strong>if we want a&nbsp;<strong>stable</strong>&nbsp;API in which our integrators can&nbsp;<strong>trust</strong>.</p>



<p>The good thing is that there are ways to build our GraphQL schema in a way that could avoid serious breaking changes in the future. When building our API, we must keep in mind that things will evolve, and to set ourselves up for success when that happens. In this post, we’ll explore a few things that can help when designing our API for the future.</p>



<h2 class="wp-block-heading" id="2d78"><a href="#1-prefer-object-types-over-simpler-structures" aria-hidden="true" class="aal_anchor" id="1-prefer-object-types-over-simpler-structures"><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. Prefer Object Types over simpler structures</h2>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="362" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1024x362.png" alt="" class="wp-image-760" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1024x362.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-300x106.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-768x271.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1536x542.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1200x424.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg.png 1580w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Take for example this&nbsp;<code>CalendarEvent</code>&nbsp;type. Notice the&nbsp;<code>timeRange</code>&nbsp;field, which represents when the event starts, and ends. At a first glance, this looks alright. We’ve got a list type, which probably matches what we have internally, represented in an array with index&nbsp;<code>0</code>&nbsp;being the start, and index&nbsp;<code>1</code>&nbsp;being the end.</p>



<p>Now what if we wanted to add some more data related to the range? For example if that time range is in the past or future? Well in it’s current state, we’d have to add a field to&nbsp;<code>CalendarEvent</code>. We’d prefix it by&nbsp;<code>timeRange</code>&nbsp;to let our integrators know they’re related. Or worst, we’d end up deprecating&nbsp;<code>timeRange</code>&nbsp;and come up with a different design for the&nbsp;<code>timeRange</code>&nbsp;field.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="408" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1024x408.png" alt="" class="wp-image-761" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1024x408.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-300x120.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-768x306.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1536x612.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1200x478.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w.png 1580w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>This looks slightly off 🤔</figcaption></figure>



<p>The problem here is that we could not add this data in the same&nbsp;<code>timeRange</code>&nbsp;field since we’re stuck with a plain&nbsp;<code>DateTime</code>&nbsp;array. What if we had designed the&nbsp;<code>timeRange</code>&nbsp;field differently to begin with? If we used an object type instead of an array here, we could’ve end up with something like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="508" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-1024x508.png" alt="" class="wp-image-762" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-1024x508.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-300x149.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-768x381.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-1200x595.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw.png 1488w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>This is much better for a few reasons:</p>



<ol class="wp-block-list"><li>We are free to add any additional data we want at no cost to the&nbsp;<code>TimeRange</code>&nbsp;type.</li><li>We have named our fields, instead of using array indexes, which is a lot funner to use for integrators.</li><li>Related data is found within a single type instead of using a field name prefix to do so.</li></ol>



<p>Try to think if the type you’re using for your field or argument is future proof. When in doubt, use a more complex structure like an object type or an input type.</p>



<h2 class="wp-block-heading" id="122d"><a href="#2-when-in-doubt-be-specific-with-naming" aria-hidden="true" class="aal_anchor" id="2-when-in-doubt-be-specific-with-naming"><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. When in Doubt, Be Specific With Naming</h2>



<p>When we start building a GraphQL Schema, the whole namespace of names is available to us. When building a new type, it’s tempting to use the simplest thing possible to describe the new entity. For example, take a&nbsp;<code>Comment</code>&nbsp;type which describes a comment on an post someone made on&nbsp;<em>SomeSocialMedia™️</em>.</p>



<p>For a while, this may work perfectly for us. However, we might eventually introduce another kind of&nbsp;<code>Comment</code>&nbsp;, and maybe this comment is actually different. This new comment class for example, might be a feedback form comment for our new app. It’s purpose is completely different, it has different fields, but also common fields.</p>



<p>Now we have to name that new comment something like&nbsp;<code>FeedbackFormComment</code>. We’re stuck with a generic&nbsp;<code>Comment</code>&nbsp;object type representing a post comment. Imagine if we wanted to come up with a&nbsp;<code>Comment</code>&nbsp;interface now that we realize we have a few types with the same behavior. Well our post comment has now stolen our generic name for the interface 😾.</p>



<p>Now we need to go through the hard and long problem of deprecating all fields with type&nbsp;<code>Comment</code>. Creating an interface with a less ideal name, removing the old fields, and finally renaming the interface to&nbsp;<code>Comment</code>. It’s not a fun thing to go through.</p>



<p>Type changes like these take 3 steps to complete:</p>



<ol class="wp-block-list"><li>Deprecate existing fields, and create new fields with a new and temporary name.</li><li>Remove all existing members with the desired name, and deprecate the newly created fields since we will rename them to the desired name.</li><li>Remove the temporary fields, and add them back with the desired name, which is now free to use.</li></ol>



<p>If we initially named our type&nbsp;<code>PostComment</code>, it would have left us some room to clearly define what a&nbsp;<code>Comment</code>&nbsp;was.</p>



<h2 class="wp-block-heading" id="50d1"><a href="#3-prefer-fields-and-types-over-custom-scalars" aria-hidden="true" class="aal_anchor" id="3-prefer-fields-and-types-over-custom-scalars"><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. Prefer Fields and Types Over Custom Scalars</h2>



<p>Some structures are hard to describe using GraphQL’s type system. For example, recursive data structures can be very hard to model with GraphQL and might require us to use a custom scalar to represent correctly.</p>



<p>In most cases though, GraphQL’s type system gives us enough tools to model anything in our schema instead of relying on JSON scalars or any custom scalars.</p>



<p>There’s a few problems with over-using custom scalars:</p>



<ol class="wp-block-list"><li>We lose any introspection ability. It’s hard for our clients to know what the shape of data will be returned from a field returning one of these scalars.</li><li>On the server side, we have now no idea on how this data is used by our integrators. It makes it very hard to make changes to the structure of those custom scalars. We can’t use GraphQL deprecation to do so since we are not using GraphQL fields within that returned payload.</li></ol>



<p>Another similar example is using strings when we could easily represent the field using an&nbsp;<code>enum</code>. For example, with a&nbsp;<code>status</code>&nbsp;field of type String, our clients need to guess the possible values for status. It makes it hard for us to add or remove values because they can’t possibly be handled by our clients. Using an enum allows clients to know when the field changes, or at least lets us use deprecations when needed.</p>



<h2 class="wp-block-heading" id="5d54"><a href="#bonus-forget-about-data-know-your-domain" aria-hidden="true" class="aal_anchor" id="bonus-forget-about-data-know-your-domain"><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>Bonus: Forget About Data, Know Your Domain!</h2>



<p>This one is a bit less practical but I still believe it’s one of the most important things we need to care about when building any API that will last and will be great to use by our integrators. When designing the shape of your GraphQL schema, try to truly understand what you’re trying to model, and understand your domain the best you can.</p>



<p>With GraphQL having a type system, we see a lot of tools appearing these days that try to generate GraphQL types from databases, ActiveRecord models, or a REST API. While this is tempting to use, and definitely useful at times, by copying our data model or an existing API, we forget to that GraphQL lets us really shape the interface we want to our domain. Try to use that power instead of shaping your API using your data’s shape as inspiration (Avoid&nbsp;<a href="https://medium.com/@__xuorig__/graphql-mutation-design-anemic-mutations-dd107ba70496" target="_blank" rel="noreferrer noopener">Anemic GraphQL</a>).</p>



<p>By doing that, implementation details can change but your API should stay stable(r) as long as we modeled our domain correctly!</p>



<p>Thank for reading ❤️ If you’ve enjoyed this post, you would probably like <a rel="noreferrer noopener" href="https://book.graphqlschemadesign.com/" target="_blank">Production Ready GraphQL</a>, a book that I worked hard on releasing. </p>


GraphQL Schema Design: Building Evolvable Schemas

Three ways to represent your GraphQL schema

Authorization in GraphQL


<p>It’s no secret that we think GraphQL is the best way to manage data in modern applications. Not only does GraphQL eliminate overfetching and unnecessary round trips to the client, it also dramatically increases developer velocity. We want to empower all developers to take advantage of these benefits, even if the thought of spinning up a GraphQL server seems intimidating at first.</p>



<p>Today, we are thrilled to announce the beta release of&nbsp;<strong>Apollo Server 2.0.&nbsp;</strong>It is designed to lower the barrier to entry for getting started with GraphQL while providing all the features teams need to run their server in production with confidence. With a schema and resolvers, you can have a production-ready GraphQL server running in less than five minutes. Let’s learn how! 🚀</p>



<h2 class="wp-block-heading" id="da72"><a href="#a-faster-path-to-adoption" aria-hidden="true" class="aal_anchor" id="a-faster-path-to-adoption"><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 faster path to adoption</h2>



<p>Once teams decide to make the transition to GraphQL, they are confronted with several choices they must make before they can start writing their first schema.</p>



<ul class="wp-block-list"><li>What language do I use?</li><li>Which server framework is best?</li><li>How do I build my schema?</li></ul>



<p>While important, these decisions slow teams down on the path to adoption. Based on years of experience building scalable, performant GraphQL applications, we’ve answered the hard questions for you with Apollo Server 2.0, so you can start running queries as quickly as possible. If you desire more flexibility, we also provide integrations for all of your favorite server frameworks, including serverless variants.</p>



<p>To get started with GraphQL, install the Apollo Server beta:</p>



<pre class="wp-block-preformatted">npm install apollo-server@beta graphql --save</pre>



<p>Next, create an instance of <code>ApolloServer</code> by passing in <code>typeDefs</code> (your schema) and <code>resolvers</code> (the functions that implement your schema). Finally, start your server by calling <code>server.listen()</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">const { ApolloServer, gql } = require(&#039;apollo-server&#039;);

// Construct a schema, using GraphQL schema language
const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// Provide resolver functions for your schema fields
const resolvers = {
  Query: {
    hello: () =&gt; &quot;world&quot;
  }
};

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) =&gt; {
  console.log(`🚀 Server ready at ${url}`)
});</code></pre>



<p>Out of the box, Apollo Server 2.0 sets up an Express server, which hosts your GraphQL API and&nbsp;<a href="https://github.com/graphcool/graphql-playground" target="_blank" rel="noreferrer noopener">GraphQL Playground</a>, an IDE that allows you to inspect your schema and run queries. If you’d like to play around with the new Apollo Server, check out our example project hosted on&nbsp;<a href="https://glitch.com/edit/#!/apollo-server-2-0-post" target="_blank" rel="noreferrer noopener"><strong>Glitch</strong></a><strong>.</strong></p>



<h2 class="wp-block-heading" id="ded8"><a href="#run-in-production-with-confidence" aria-hidden="true" class="aal_anchor" id="run-in-production-with-confidence"><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>Run in production with confidence</h2>



<p>Although we’ve simplified the Apollo Server API, we haven’t compromised on features! Apollo Server 2.0 introduces built-in support for GraphQL subscriptions, powerful error handling tools, schema stitching, and schema directives.</p>



<p>We’ve also made it easier to gain visibility into what’s happening with your GraphQL API with opt-in&nbsp;<a href="https://engine.apollographql.com/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;integration. Engine is a GraphQL gateway that sits in between the client and your GraphQL server. It unlocks necessary features for running GraphQL in production such as performance monitoring, caching, persisted queries, and schema analytics.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="451" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-1024x451.png" alt="" class="wp-image-788" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-1024x451.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-300x132.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-768x338.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-1536x676.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-2048x902.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-1200x528.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Qy6PKjLOvWZz-fEDlCCMsg-1980x872.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>The Apollo Engine tracing view helps you understand your GraphQL API</figcaption></figure>



<p>Setting up Apollo Engine has never been faster — just install&nbsp;<code>apollo-engine</code>, pass&nbsp;<code>engine: true</code>&nbsp;to your server configuration, and provide an&nbsp;<code>ENGINE_API_KEY</code>&nbsp;as an environment variable. If you’d like to try it out,&nbsp;<a href="https://engine.apollographql.com/" target="_blank" rel="noreferrer noopener">create an Engine service</a>&nbsp;to receive an API key,&nbsp;<a href="https://glitch.com/edit/#!/dog-graphql-api" target="_blank" rel="noreferrer noopener">remix this sample project on Glitch</a>, and add your API key to the&nbsp;<code>.env</code>&nbsp;file.</p>



<h2 class="wp-block-heading" id="810f"><a href="#a-bright-future-%f0%9f%9a%80" aria-hidden="true" class="aal_anchor" id="a-bright-future-%f0%9f%9a%80"><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 bright future 🚀</h2>



<p>After setting up a server, what’s next? We want to guide you along your GraphQL journey by providing all of the advice and best practices you need to architect your schema. Look no further than the revamped Apollo Server docs, which now support&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/" target="_blank" rel="noreferrer noopener">multiple versions!</a></p>



<p>If you’re new to GraphQL, check out our improved <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/apollo-server/v2/getting-started.html" target="_blank">getting started guide</a>. We’ve also added new essentials guides explaining important GraphQL concepts such as <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/apollo-server/v2/essentials/schema.html" target="_blank">building a schema</a> and <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/apollo-server/v2/essentials/data.html" target="_blank">fetching data with resolvers</a>. If you’re an advanced user, be on the lookout for pages on deployment, schema stitching, and schema directives coming soon. Expect the new docs to improve even more in the weeks leading up to the official release.</p>



<figure class="wp-block-embed-twitter wp-block-embed is-type-rich is-provider-twitter"><div class="wp-block-embed__wrapper">
<blockquote class="twitter-tweet" data-width="550" data-dnt="true"><p lang="en" dir="ltr">👀 it looks like the next version of Apollo Server will be able to actually run inside <a href="https://twitter.com/Cloudflare?ref_src=twsrc%5Etfw">@Cloudflare</a> workers at the edge! <a href="https://twitter.com/hashtag/GraphQL?src=hash&amp;ref_src=twsrc%5Etfw">#GraphQL</a> <a href="https://t.co/rGSDigIztm">pic.twitter.com/rGSDigIztm</a></p>&mdash; Apollo (@apollographql) <a href="https://twitter.com/apollographql/status/991499774984507393?ref_src=twsrc%5Etfw">May 2, 2018</a></blockquote><script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
</div></figure>



<p>This is just the beginning for how we develop and deploy GraphQL servers. We think there are amazing new paradigms to explore in how data can be cached, queried, and distributed all around the world with Apollo Server. We’ve even made progress on experimental features such as running GraphQL on the edge via&nbsp;<a href="https://github.com/jbaxleyiii/apollo-server-cloudflare" target="_blank" rel="noreferrer noopener">Cloudflare workers</a>.</p>



<p>With tighter integrations between Apollo Client and Apollo Server in the works, teams will be able to take advantage of more efficient transports, integrated caching from schema to UI components, and even long talked about features like&nbsp;<code>@defer</code>&nbsp;support. The new Apollo Server 2.0 beta brings us closer to making these features a reality.</p>



<p>We would love for teams to try out the Apollo Server 2.0 beta and give us feedback! If you’re currently using Apollo Server 1.0, you don’t have to worry about any breaking changes when you upgrade. If you would like to switch to the new API, be sure to read our comprehensive&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/migration-two-dot.html" target="_blank" rel="noreferrer noopener">migration guide</a>. If you’re new to Apollo Server, our&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/v2/getting-started.html" target="_blank" rel="noreferrer noopener">getting started guide</a>&nbsp;will help you go from zero to GraphQL quickly. As always, please get in touch on&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">Twitter</a>&nbsp;or&nbsp;<a href="https://www.apollographql.com/slack" target="_blank" rel="noreferrer noopener">Apollo Slack</a>&nbsp;if you’d like to help build the next generation of GraphQL servers.</p>


Try out the Apollo Server 2.0 beta!


<p>A few months ago, we&nbsp;<a href="https://dev-blog.apollodata.com/graphql-tools-2-0-with-schema-stitching-8944064904a5" target="_blank" rel="noreferrer noopener">launched</a>&nbsp;the first version of a new concept called “schema stitching” in graphql-tools 2.0. Schema stitching is a way to combine multiple GraphQL APIs together, or use an existing API in the construction of a new one. Since the launch, we’ve been excited to see this concept gain a ton of traction in the GraphQL community and we’re more confident than ever that this is going to be a promising long-term direction.</p>



<p>Here are some of best use cases we’ve seen:</p>



<ol class="wp-block-list"><li>Developing your GraphQL API as a set of microservices, and then stitching them together to create one complete API</li><li>Using&nbsp;<a href="https://www.prisma.io/" target="_blank" rel="noreferrer noopener">Prisma</a>, a GraphQL database layer that lets you work with MySQL or Postgres, as part of your GraphQL schema</li><li>Using a public or internal existing API as part of a new GraphQL schema you’re building</li></ol>



<p>Since the original launch of schema stitching last year, we’ve learned a ton about these different use cases, so we set out to improve the API to better support what we’ve seen.</p>



<p><strong>Today, we’re excited to release graphql-tools 3.0, a major improvement to how schema stitching works.</strong></p>



<p>It also comes with some new abstractions to support more extensibility in the future. It’s completely&nbsp;<strong>backwards compatible</strong>, meaning your existing code will still work as-is, but we’ve updated the recommended approach so we felt a major version bump was appropriate.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This new feature and the blog post you’re reading now was developed by&nbsp;<a href="https://medium.com/u/51db47a6a4ef?source=post_page-----2716b3b259c0----------------------" target="_blank" rel="noreferrer noopener">Mikhail Novikov</a>&nbsp;and&nbsp;<a href="https://medium.com/u/540bbf1a0d2b?source=post_page-----2716b3b259c0----------------------" target="_blank" rel="noreferrer noopener">Ben Newman</a>. Mikhail is currently available for remote GraphQL contract work, so contact him at&nbsp;<a href="mailto:freiksenet@reindex.io" target="_blank" rel="noreferrer noopener">freiksenet@reindex.io</a>&nbsp;if you need some GraphQL help.</p></blockquote>



<h3 class="wp-block-heading" id="a136"><a href="#making-it-easier-to-modify-schemas-and-handle-conflicts" aria-hidden="true" class="aal_anchor" id="making-it-easier-to-modify-schemas-and-handle-conflicts"><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>Making it easier to modify schemas and handle conflicts</h3>



<p>After gathering a lot of feedback from beta users, we think we have found an improved API that is simpler and more flexible:</p>



<ol class="wp-block-list"><li>It’s easier to modify schemas before or after you stitch them together</li><li>It’s easier to identify and avoid schema conflicts by namespacing</li></ol>



<p>This is enabled by a new concept called&nbsp;<strong>schema transforms.</strong>&nbsp;These are functions you can apply to a schema to do things like rename or filter types or fields.</p>



<p>To get started, read about&nbsp;<a href="https://www.apollographql.com/docs/graphql-tools/schema-stitching.html" target="_blank" rel="noreferrer noopener">schema stitching</a>&nbsp;and&nbsp;<a href="https://www.apollographql.com/docs/graphql-tools/schema-transforms.html" target="_blank" rel="noreferrer noopener">schema transforms</a>&nbsp;in the new docs. To get the full details, check out the&nbsp;<a href="https://github.com/apollographql/graphql-tools/blob/master/CHANGELOG.md#v300" target="_blank" rel="noreferrer noopener">change log</a>.</p>



<p>To learn about the new concepts, read on!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="538" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/0_B7pF0zu5Ubn7tmT0-1024x538.jpg" alt="" class="wp-image-790" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/0_B7pF0zu5Ubn7tmT0-1024x538.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_B7pF0zu5Ubn7tmT0-300x158.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_B7pF0zu5Ubn7tmT0-768x404.jpg 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_B7pF0zu5Ubn7tmT0.jpg 1200w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



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



<p>When you start using GraphQL, you usually have exactly one schema. But as usage progresses at your company, you often end up with multiple. Perhaps that’s because different teams developed a GraphQL API in parallel, or maybe you’re using a GraphQL database layer like Prisma which comes with its own schema, or you’re trying to build a new layer over an existing GraphQL API.</p>



<p>Once you have multiple schemas, you can start thinking of them as the building blocks of data in your organization. If you’re going to use them as building blocks, sometimes you’ll need to make modifications to a schema for it to fit your needs.</p>



<p>Until now, it has been very difficult to make a change to a schema and still be able to run arbitrary queries against it. With the schema transformation functionality in graphql-tools 3.0, that’s now easier than ever before.</p>



<h3 class="wp-block-heading" id="de1e"><a href="#example-renaming-a-type" aria-hidden="true" class="aal_anchor" id="example-renaming-a-type"><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>Example: Renaming a type</h3>



<p>Let’s look at an example to see why it’s difficult to rename a type in a GraphQL schema you don’t control. In this case, let’s say we’re trying to use the GitHub API schema as part of our app’s schema, but we don’t want the&nbsp;<code>User</code>&nbsp;types to conflict. That means we might want to rename GitHub’s&nbsp;<code>User</code>&nbsp;type to&nbsp;<code>GitHubUser</code>. If we still want to be able to send queries to this part of our schema, we need to handle a lot of different cases:</p>



<ol class="wp-block-list"><li>Results that have&nbsp;<code>__typename</code>&nbsp;need to replace any occurrence of&nbsp;<code>User</code>&nbsp;with&nbsp;<code>GitHubUser</code></li><li>Queries that have fragments need to replace&nbsp;<code>on GitHubUser</code>&nbsp;with&nbsp;<code>on User</code>&nbsp;before sending the query to GitHub</li><li>When the schema is introspected, it needs to return&nbsp;<code>GitHubUser</code>&nbsp;for the name of the type everywhere, including when it’s a member of a union or interface</li></ol>



<p>So it’s not as easy as just taking the GitHub schema object and renaming the type — we need to correctly transform the queries and results as well. Transforming the query and result, in addition to the schema itself, is what a schema transform does in graphql-tools 3.0.</p>



<p>Here’s how we could rename a type in a remote GitHub schema using the new&nbsp;<code>transformSchema</code>&nbsp;method:</p>



<pre class="wp-block-preformatted">import {<br>  makeRemoteExecutableSchema,<br>  transformSchema,<br>  RenameTypes,<br>} from 'graphql-tools';// Make a schema that points to the GitHub API<br>const gitHubSchema = makeRemoteExecutableSchema(...);const transformedSchema = transformSchema(gitHubSchema, [<br>  new RenameTypes((name) =&gt; {<br>    if (name === 'User') {<br>      return 'GitHubUser';<br>    }    return name;<br>  }<br>]);const result = graphql(transformedSchema, `<br>  query {<br>    viewer {<br>      __typename<br>      ... on GitHubUser {<br>        username<br>      }<br>    }<br>  }<br>`);</pre>



<p>You can see that in the query we use the&nbsp;<em>new</em>&nbsp;name for the type,&nbsp;<code>GitHubUser</code>, but the query that gets sent to the GitHub API will refer to the original&nbsp;<code>User</code>&nbsp;type. Also, while the GitHub API will return their&nbsp;<code>__typename</code>, response types named&nbsp;<code>User</code>&nbsp;will also be replaced correctly with&nbsp;<code>GitHubUser</code>.</p>



<p>Basically, using&nbsp;<code>transformSchema</code>&nbsp;here enables us to reshape a GraphQL schema at will, while making sure all queries work as expected. This is critical so that we can do namespacing, avoid schema conflicts when stitching, and limit access to only the fields we want.</p>



<h2 class="wp-block-heading" id="61c5"><a href="#built-in-transforms" aria-hidden="true" class="aal_anchor" id="built-in-transforms"><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>Built-in transforms</h2>



<p>The graphql-tools 3.0 release comes with a set of transforms pre-implemented for you, based on the set of feature requests we have received for the previous version of schema stitching. We think these will make it easy to address many cases of schema transformation, filtering, and namespacing you encounter.</p>



<h3 class="wp-block-heading" id="985c"><a href="#filtering" aria-hidden="true" class="aal_anchor" id="filtering"><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>Filtering</h3>



<p>These allow you to select just part of a schema.</p>



<ul class="wp-block-list"><li><code>FilterRootFields</code>: Filter the entry points into a schema, so clients don’t have access to all of the&nbsp;<code>Query</code>/<code>Mutation</code>&nbsp;fields of the underlying schema.</li><li><code>FilterTypes</code>: Allows you to remove some types from the schema by name.</li></ul>



<h3 class="wp-block-heading" id="bac7"><a href="#renaming" aria-hidden="true" class="aal_anchor" id="renaming"><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>Renaming</h3>



<p>These allow you to rename parts of the schema.</p>



<ul class="wp-block-list"><li><code>RenameRootFields</code>: Rename fields on the&nbsp;<code>Query</code>&nbsp;and&nbsp;<code>Mutation</code>&nbsp;types.</li><li><code>RenameTypes</code>: Rename types (and any references to those types) throughout the schema.</li></ul>



<h2 class="wp-block-heading" id="691b"><a href="#implementing-your-own-transforms" aria-hidden="true" class="aal_anchor" id="implementing-your-own-transforms"><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>Implementing your own transforms</h2>



<p>While the above transforms should be adequate to get you started, it’s also pretty easy to implement your own. You just need to implement one or more methods of the following interface:</p>



<pre class="wp-block-preformatted">type Transform = {<br>  transformSchema?: (schema: GraphQLSchema) =&gt; GraphQLSchema;<br>  transformRequest?: (request: Request) =&gt; Request;<br>  transformResult?: (result: Result) =&gt; Result;                       };</pre>



<p>This describes the three things that a schema transform needs to handle, like we mentioned above:</p>



<ol class="wp-block-list"><li>Transforming the&nbsp;<code>GraphQLSchema</code>&nbsp;object itself</li><li>Transforming incoming GraphQL requests — queries and their variables</li><li>Transforming outgoing result objects</li></ol>



<p>Not all transforms need to handle each method — for example, some transformations might just need to process the schema and requests, but not results. For inspiration, take a look at the existing transforms, for example&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/graphql-tools/blob/79868c597145a04e896677720769f15ee2b386b9/src/transforms/RenameTypes.ts&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;RenameTypes&lt;/a&gt;</code>.</p>



<h2 class="wp-block-heading" id="c268"><a href="#combining-schema-transforms-and-stitching" aria-hidden="true" class="aal_anchor" id="combining-schema-transforms-and-stitching"><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>Combining schema transforms and stitching</h2>



<p>The main use case for which we designed the current version of schema transforms is to avoid naming collisions or exposing unnecessary fields during stitching. For that use case, you simply remove the fields you don’t want to expose, or rename types before you stitch the schema. But what happens when you don’t want to have a certain root field in the result schema, but you still need it for stitching?</p>



<p>Well, it turns out that you can <em>delegate</em> to the original, untransformed schema by keeping both objects around:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { 
  transformSchema,
  mergeSchemas,
  FilterRootFields,
  RenameTypes,
  RenameRootFields,
} from &#039;graphql-tools&#039;;

// Transform the schema to namespace it and only keep one root field
const transformedChirpSchema = transformSchema(chirpSchema, [
  new FilterRootFields((operation: string, rootField: string) =&gt;
    [&#039;Query.chirpById&#039;].includes(`${operation}.${rootField}`),
  ),
  new RenameTypes((name: string) =&gt; `Chirp_${name}`),
  new RenameRootFields((name: string) =&gt; `Chirp_${name}`),
]);

const schema = mergeSchemas({
  schemas: [
    // Use the transformed schema for merging, so that we only
    // get the fields we want
    transformedChirpSchema,
    authorSchema,
    linkTypeDefs,
  ],
  resolvers: {
    User: {
      chirps: {
        fragment: `fragment UserFragment on User { id }`,
        resolve(parent, args, context, info) {
          const authorId = parent.id;
          return info.mergeInfo.delegateToSchema({
            // Use the original unfilitered schema for delegation
            // since we need the fields we filtered out for merging
            schema: chirpSchema,
            operation: &#039;query&#039;,
            // This field is not accessible in the transformed schema
            fieldName: &#039;chirpsByAuthorId&#039;,
            args: {
              authorId,
            },
            context,
            info,
            
            // Apply transforms here for type renaming
            transforms: transformedChirpSchema.transforms,
           });
        },
      },
    },
  },
},</code></pre>



<p>The key function here is&nbsp;<code>info.mergeInfo.delegateToSchema</code>, which makes it easy to implement resolvers in terms of any existing schema.</p>



<p>This new function for delegation now also takes a set of transforms as a parameter, allowing you to pick and choose the transforms you want for a specific delegation. We hope that people can build abstractions around this to take advantage of the ultimate flexibility offered by this new approach.</p>



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



<h2 class="wp-block-heading" id="92f5"><a href="#next-steps" aria-hidden="true" class="aal_anchor" id="next-steps"><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>Next steps</h2>



<p>With graphql-tools 3.0, we wanted to bring you this new, simplified way to handle schema conflicts as soon as possible. But we think the potential for schema transforms is going to be huge as more and more people see schemas as the building blocks of their organization’s data. If you’re interested in implementing some new transforms for your use cases, let us know!</p>


The next generation of schema stitching


<p>One of our core tenets on the Apollo team is that we want to enable you to use GraphQL in a way that works with your existing technology investments.&nbsp;It’s much easier to convince your coworkers that the benefits of GraphQL are worth the effort if you can bring your favorite tools with you.</p>



<p>There are tons of software-as-a-service platforms developers use every day to understand and manage their apps. We see&nbsp;<a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>, our service for GraphQL management and insights, as the natural nexus point between these services and your GraphQL API. Engine handles the GraphQL-specific parts, and can hand off the data to the other tools you use.</p>



<p>That’s why recently, we’ve been working hard on integrating Engine’s GraphQL-specific features with:</p>



<ol class="wp-block-list"><li><a href="https://dev-blog.apollodata.com/caching-graphql-results-in-your-cdn-54299832b8e2" target="_blank" rel="noreferrer noopener">CDNs, like CloudFlare, Fastly, and Akamai,</a></li><li><a href="https://dev-blog.apollodata.com/daily-slack-reports-of-your-graphql-query-performance-and-errors-1749311f33e1" target="_blank" rel="noreferrer noopener">Slack, with daily overview reports of your API,</a>&nbsp;and</li><li><a href="https://dev-blog.apollodata.com/introducing-alerts-in-apollo-engine-e32eeb03b7fa" target="_blank" rel="noreferrer noopener">PagerDuty, with custom triggered alerts</a></li></ol>



<p>Today, we’re introducing another commonly-requested integration: The ability to pipe metrics into&nbsp;<strong>Datadog</strong>, a popular monitoring and analytics platform!</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="337" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/0_r3Lsla2HF4xNIgri-1024x337.png" alt="" class="wp-image-795" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/0_r3Lsla2HF4xNIgri-1024x337.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_r3Lsla2HF4xNIgri-300x99.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_r3Lsla2HF4xNIgri-768x253.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_r3Lsla2HF4xNIgri.png 1194w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Seeing your GraphQL operation latency in Datadog</figcaption></figure>



<p>We’ve been using this feature ourselves and testing it with some early access customers, and it’s allowed us to easily integrate GraphQL-specific information from our API into our existing backend monitoring dashboard.</p>



<p>Datadog integration is one of the newest features of our Engine&nbsp;<a href="https://www.apollographql.com/engine/#plans" target="_blank" rel="noreferrer noopener">Standard and Pro plans</a>, which also include benefits like much longer data retention and&nbsp;<a href="https://dev-blog.apollodata.com/introducing-alerts-in-apollo-engine-e32eeb03b7fa" target="_blank" rel="noreferrer noopener">proactive alerting</a>. If you’re on Community edition today, you can try it out for two weeks with no credit card required!</p>



<p><em>If you haven’t added Engine to your API yet, read the&nbsp;</em><a href="https://www.apollographql.com/docs/engine/setup-node.html" target="_blank" rel="noreferrer noopener"><em>setup directions here</em></a><em>&nbsp;or learn more&nbsp;</em><a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener"><em>on the website</em></a><em>.</em></p>



<h2 class="wp-block-heading" id="56ac"><a href="#information-provided-to-datadog" aria-hidden="true" class="aal_anchor" id="information-provided-to-datadog"><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>Information provided to Datadog</h2>



<p>Almost all of the performance and error statistics you can see in the Engine UI are exported through the integration. With today’s integration, you can get:</p>



<ul class="wp-block-list"><li>Request rates,</li><li>Error rates,</li><li>Cache hit rates, and</li><li>Latency histogram statistics</li></ul>



<p>But it’s much better than just that, since Engine embeds extra information in the data it passes on.</p>



<h3 class="wp-block-heading" id="b6df"><a href="#graphql-operation-tagging" aria-hidden="true" class="aal_anchor" id="graphql-operation-tagging"><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>GraphQL operation tagging</h3>



<p>The data sent to Datadog is tagged with GraphQL-specific information, like the name of the GraphQL operation. That way, you can easily filter down to a specific query or mutation by using the provided tags.</p>



<p>Here’s what it looks like in the Datadog UI:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="964" height="950" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_TFVhZOccdYX185jcLZl4wQ.png" alt="" class="wp-image-794" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_TFVhZOccdYX185jcLZl4wQ.png 964w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TFVhZOccdYX185jcLZl4wQ-300x296.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TFVhZOccdYX185jcLZl4wQ-768x757.png 768w" sizes="auto, (max-width: 964px) 100vw, 964px" /></figure>



<p>This allows you to integrate any information you want to know about your GraphQL API’s specific operations into your existing Datadog dashboards.</p>



<p>Here’s what one of our operations looks like in a chart:</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="426" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA-1024x426.png" alt="" class="wp-image-793" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA-1024x426.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA-300x125.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA-768x319.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA-1536x639.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA-1200x499.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0O0yMv1JUhqKWPN6AnvCHA.png 1924w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>Integrating your GraphQL data into a sophisticated monitoring service lik Datadog has additional benefits beyond just being able to see charts. Even though you can get alerts directly from Engine, you also can get sophisticated alerting based on the data piped into Datadog. In particular, you can use&nbsp;<a href="https://docs.datadoghq.com/monitors/monitor_types/composite/" target="_blank" rel="noreferrer noopener">composite alerts</a>&nbsp;to trigger an alert based on a combination of factors, for example to get notified when an operation’s error rate&nbsp;<em>and</em>&nbsp;latency go up.</p>



<h2 class="wp-block-heading" id="0188"><a href="#setting-it-up" aria-hidden="true" class="aal_anchor" id="setting-it-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>Setting it up</h2>



<p>Setting up Datadog with Engine is easy.&nbsp;<a href="https://www.apollographql.com/docs/engine/datadog.html" target="_blank" rel="noreferrer noopener">Get the full details in the docs</a>, but it’s just a few steps:</p>



<ol class="wp-block-list"><li>Get a new API key from the&nbsp;<a href="https://app.datadoghq.com/account/settings#api" target="_blank" rel="noreferrer noopener">Datadog API integrations page</a></li><li>In Engine, go to the settings for your service, and enable Datadog integration</li><li>Paste in your API key from Datadog</li></ol>



<p>Since metrics are tagged with the service they came from, you can use the same key for all of your services.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="800" height="192" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/0_OtoRRrNQpP-1J8jH.png" alt="" class="wp-image-792" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/0_OtoRRrNQpP-1J8jH.png 800w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_OtoRRrNQpP-1J8jH-300x72.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_OtoRRrNQpP-1J8jH-768x184.png 768w" sizes="auto, (max-width: 800px) 100vw, 800px" /><figcaption>Think of the satisfaction you’ll get when this button is green and you can see all your metrics coming in! 📈</figcaption></figure>



<h2 class="wp-block-heading" id="1ce1"><a href="#engine-bringing-together-all-your-services" aria-hidden="true" class="aal_anchor" id="engine-bringing-together-all-your-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>Engine: Bringing together all your services</h2>



<p>When you go into production with a new GraphQL API, you don’t want to leave all of your existing tooling behind. We all rely on tools like Datadog to bring together our data and operate services, and GraphQL needs these just like any other technology.</p>



<p>But usually, these services don’t integrate directly into a GraphQL API, so you can’t filter by things like your operation name. Plus, once you identify a problem you might need to dive into specific traces and reports to see what needs to be changed.</p>



<p>That’s why I’m really excited about&nbsp;<a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;integrating with the world of developer services — Engine can handle all of the GraphQL-specific bits, and enable you to keep using the tooling you need to do your work. And this is just the beginning; stay tuned for more.</p>



<p>Let us know&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">on Twitter</a>&nbsp;if you have other ideas for services you’d like to see integrated with GraphQL and Engine!</p>


Sending GraphQL metrics to Datadog with Apollo Engine


<p>As your GraphQL application grows from demo, to proof of concept, to production, the complexity of your schema and resolvers will grow in tandem. To organize your code, you’ll want to split up your schema types and the associated resolvers into multiple files.</p>



<p>We get this question frequently since there are a lot of different approaches to splitting up your schema code, and it might seem that you need a complex setup to get a good result. But it turns out that we can arrange our schema and resolver code in separate files with just a few simple JavaScript concepts.</p>



<p>In this post, we present a straightforward method for modularizing schemas built with&nbsp;<code>graphql-tools</code>&nbsp;that you can tweak to match your tastes and your codebase.</p>



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



<p>If you’re just starting out and have your entire schema defined in one file, it might look much like the below snippet. Here, we’ll call it&nbsp;<code>schema.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// schema.js

const typeDefs = `
  type Query {
    author(id: Int!): Post
    book(id: Int!): Post
  }  

  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }  

  type Book {
    title: String
    author: Author
  }
`;

makeExecutableSchema({
  typeDefs: typeDefs,
  resolvers: {},
});</code></pre>



<p>Ideally, instead of having everything in one schema definition string, we’d like to put the schema types for&nbsp;<code>Author</code>&nbsp;and&nbsp;<code>Book</code>&nbsp;in files called&nbsp;<code>author.js</code>&nbsp;and&nbsp;<code>book.js</code>.</p>



<p>At the end of the day, the schema definitions we’ve written in the Schema Definition Language (SDL) are just strings. Treating them as such, we have a simple way of importing type definitions across different files: Split up the string into multiple strings that we can combine later. This is what&nbsp;<code>author.js</code>&nbsp;would look like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// author.js
export const typeDef = `
  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }
`;</code></pre>



<p>Here’s&nbsp;<code>book.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// book.js
export const typeDef = `
  type Book {
    title: String
    author: Author
  }
`;</code></pre>



<p>Finally, we pull it all together in&nbsp;<code>schema.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// schema.js
import { typeDef as Author } from &#039;./author.js&#039;;
import { typeDef as Book } from &#039;./book.js&#039;;

const Query = `
  type Query {
    author(id: Int!): Post
    book(id: Int!): Post
  }
`;

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers: {},
});</code></pre>



<p>We’re not doing anything fancy here: we’re just importing strings that happen to contain some SDL. Note that for convenience you don’t need to combine the strings yourself —&nbsp;<code>makeExecutableSchema</code>&nbsp;can actually accept an array of type definitions directly to facilitate this approach.</p>



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



<p>Now that we have a way to chop up our schema into logical parts, we want to be able to move each resolver with its associated part of the schema as well. In general, we want to keep resolvers for a certain type in the same file as the schema definition for that type.</p>



<p>Expanding on our previous example, here’s our&nbsp;<code>schema.js</code>&nbsp;file with some resolvers added into the picture:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// schema.js
import { typeDef as Author } from &#039;./author.js&#039;;
import { typeDef as Book } from &#039;./book.js&#039;;

const Query = `
  type Query {
    author(id: Int!): Post
    book(id: Int!): Post
  }
`;

const resolvers = {
  Query: {
    author: () =&gt; { ... },
    book: () =&gt; { ... },
  },
  Author: {
    name: () =&gt; { ... },
  },
  Book: {
    title: () =&gt; { ... },
  },
};

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers,
});</code></pre>



<p>Just like we split up the schema definition string, we can split up the&nbsp;<code>resolvers</code>&nbsp;object. We can put a piece of it in&nbsp;<code>author.js</code>, another in&nbsp;<code>book.js</code>, and then import them and use the&nbsp;<code>lodash.merge</code>&nbsp;function to put it all together in&nbsp;<code>schema.js</code>.</p>



<p>Here’s what&nbsp;<code>author.js</code>&nbsp;would look like in that case:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// author.js
export const typeDef = `
  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }
`;

export const resolvers = {
  Author: {
    books: () =&gt; { ... },
  }
};</code></pre>



<p>Here’s&nbsp;<code>book.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// book.js
export const typeDef = `
  type Book {
    title: String
    author: Author
  }
`;

export const resolvers = {
  Book: {
    author: () =&gt; { ... },
  }
};</code></pre>



<p>Then, we apply&nbsp;<code>lodash.merge</code>&nbsp;in&nbsp;<code>schema.js</code>&nbsp;to put everything together:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { merge } from &#039;lodash&#039;;
import { 
  typeDef as Author, 
  resolvers as authorResolvers,
} from &#039;./author.js&#039;;
import { 
  typeDef as Book, 
  resolvers as bookResolvers,
} from &#039;./book.js&#039;;

const Query = `
  type Query {
    author(id: Int!): Author
    book(id: Int!): Book
  }
`;

const resolvers = {
  Query: { 
    ...,
  }
};

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers: merge(resolvers, authorResolvers, bookResolvers),
});</code></pre>



<p>And that gives us the&nbsp;<code>resolvers</code>&nbsp;structure that we started out with!</p>



<h2 class="wp-block-heading" id="14ac"><a href="#extending-types-in-multiple-files" aria-hidden="true" class="aal_anchor" id="extending-types-in-multiple-files"><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>Extending types in multiple files</h2>



<p>We’re still defining&nbsp;<code>authors</code>&nbsp;and&nbsp;<code>books</code>&nbsp;as top-level fields on&nbsp;<code>Query</code>&nbsp;within&nbsp;<code>schema.js</code>, even though these are logically tied to&nbsp;<code>Author</code>&nbsp;and&nbsp;<code>Book</code>&nbsp;and should live in&nbsp;<code>author.js</code>&nbsp;and&nbsp;<code>book.js</code>.</p>



<p>To accomplish that, we can use type extensions. We can define our existing&nbsp;<code>Query</code>&nbsp;type like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const Query = `
  type Query {
    _empty: String
  }
  
  extend type Query {
    author(id: Int!): Author 
  }
  
  extend type Query {
    book(id: Int!): Book 
  }
`;</code></pre>



<p><em>Note: In the current version of GraphQL, you can’t have an empty type even if you intend to extend it later. So we need to make sure the Query type has at least one field — in this case we can add a fake _empty field. Hopefully in future versions it will be possible to have an empty type to be extended later.</em></p>



<p>Basically, the&nbsp;<code>extend</code>&nbsp;keyword lets us add fields to an already-defined type. We can use this keyword in order to define Query fields relevant to those types in&nbsp;<code>book.js</code>&nbsp;and&nbsp;<code>author.js</code>. We should then also move to defining the Query resolvers for those types in the same place.</p>



<p>Here’s what&nbsp;<code>author.js</code>&nbsp;looks like with this approach:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">// author.js

export const typeDef = `
  extend type Query {
    author(id: Int!): Author
  }  
  
  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }
`;

export const resolvers = {
  Query: {
    author: () =&gt; { ... },
  },
  Author: {
    books: () =&gt; { ... },
  }
};</code></pre>



<p>This is what&nbsp;<code>book.js</code>&nbsp;looks like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// book.js

export const typeDef = `
  extend type Query {
    book(id: Int!): Book
  }  

  type Book {
    title: String
    author: Author
  }
`;

export const resolvers = {
  Query: {
    book: () =&gt; { ... },
  },
  Book: {
    author: () =&gt; { ... },
  }
};</code></pre>



<p>Just as before, we put it all together in&nbsp;<code>schema.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { merge } from &#039;lodash&#039;;
import { 
  typeDef as Author, 
  resolvers as authorResolvers,
} from &#039;./author.js&#039;;
import { 
  typeDef as Book, 
  resolvers as bookResolvers,
} from &#039;./book.js&#039;; 

// If you had Query fields not associated with a
// specific type you could put them here
const Query = `
  type Query {
    _empty: String
  }
`;

const resolvers = {};

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers: merge(resolvers, authorResolvers, bookResolvers),
});</code></pre>



<p>Now, the schema and resolver definitions are properly co-located with the associated types!</p>



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



<p>We’ve just been through the mechanics of modularizing your server code. Here are a few additional tips that may be helpful in figuring out how to carve up your codebase:</p>



<ol class="wp-block-list"><li>When learning, prototyping or even building a POC, putting your whole schema in a single file is likely fine: There are benefits to be able to go through your whole schema really quickly, or explain it to a coworker.</li><li>You can organize your schema and resolvers by feature: for example, putting the stuff related to the checkout system together might make sense in an ecommerce site.</li><li>Keep your resolvers in the same file as the schema definition for the fields they implement. This will allow you to reason about your code efficiently.</li><li>Wrap your SDL type definitions with a&nbsp;<code>gql</code>&nbsp;tag using&nbsp;<a href="https://github.com/apollographql/graphql-tag" target="_blank" rel="noreferrer noopener">graphql-tag</a>. If you’re using a GraphQL plugin for your editor or formatting your code with Prettier, you’ll be able to get syntax highlighting for SDL within your code editor as long as you prefix it with the&nbsp;<code>gql</code>&nbsp;tag.</li></ol>



<p>Now, go forth and organize your code!</p>


Modularizing your GraphQL schema code


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This is a guest post by Mikhail Novikov, who worked on GraphQL schema delegation and schema stitching in the&nbsp;<a href="https://github.com/apollographql/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools library</a>. He is currently available for remote GraphQL contract work. Contact him at&nbsp;<a href="mailto:freiksenet@reindex.io" target="_blank" rel="noreferrer noopener">freiksenet@reindex.io</a>&nbsp;if you need some GraphQL help.</p></blockquote>



<p>In this article I’m going to talk about schema delegation — a way to automatically forward a GraphQL query (or a part of it) to another schema.&nbsp;Schema delegation allows reusing parts of other schemas without manually querying them.&nbsp;Examples where schema delegation would be particularly appropriate include:</p>



<ul class="wp-block-list"><li>Building a GraphQL gateway that would forward queries to underlying GraphQL microservices</li><li>Using a third-party GraphQL API as part of your schema</li><li>Using a GraphQL database proxy like&nbsp;<a href="https://www.prisma.io/" target="_blank" rel="noreferrer noopener">Prisma</a></li></ul>



<h2 class="wp-block-heading" id="0a07"><a href="#implementing-a-graphql-gateway" aria-hidden="true" class="aal_anchor" id="implementing-a-graphql-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>Implementing a GraphQL gateway</h2>



<p>Let’s consider a GraphQL service for a basic blog API. The schema has two types —&nbsp;<code>User</code>&nbsp;and&nbsp;<code>Blog</code>. It also has root fields to retrieve them by their&nbsp;<code>_id</code>. On top of the service there is a GraphQL gateway implementing a&nbsp;<code>Node</code>&nbsp;interface for the types of an underlying GraphQL service.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><code>Node</code>&nbsp;is a common interface in the GraphQL world which indicates any object that can be globally addressed by some&nbsp;<code>id</code>. It’s usually coupled with a root field called&nbsp;<code>node</code>, which returns any object of a type that implements&nbsp;<code>Node</code>, by id. You can read more about&nbsp;<code>Node</code>&nbsp;interface in&nbsp;<a href="https://facebook.github.io/relay/graphql/objectidentification.htm" target="_blank" rel="noreferrer noopener">this article</a>.</p></blockquote>



<p>The gateway reuses the same <code>User</code> and <code>Blog</code> types extending them so that they implement the <code>Node</code> interface. It also provides <code>node</code> root field on top of the two existing ones. Here are the schemas for the service and the gateway.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type User {
  _id: ID!
  username: String
  blogs: [Blog]
}

type Blog {
  _id: ID!
  user: User
  title: String!
  text: String
}

type Query {
  userById(id: ID!): User
  blogById(id: ID!): Blog
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">interface Node {
  id: ID!
}

extend type User implements Node {
  id: ID!
}

extend type Blog implements Node {
  id: ID!
}

extend type Query {
  node(id: ID!): Node
}</code></pre>



<p>Instead of reimplementing&nbsp;<code>userById</code>&nbsp;and&nbsp;<code>blogById</code>&nbsp;in the gateway, it will execute the query using the service schema. To do it, you could build the query from the information you get as the fourth argument of a resolver —&nbsp;<code>GraphQLResolveInfo</code>. It has the subquery starting at the current resolver (<code>fieldNodes</code>), fragments used in the operation (<code>fragments</code>) and variables in&nbsp;<code>operation</code>. Out of this information you could create a GraphQL&nbsp;<code>Document</code>,&nbsp;<code>print</code>&nbsp;it and send it to the service schema.</p>



<p>For the root fields that match with the service fields you don’t need to do anything else. As for the new fields like&nbsp;<code>node</code>&nbsp;you also need to change the name of the root field depending on the global&nbsp;<code>id</code>.</p>



<h3 class="wp-block-heading" id="06f1"><a href="#filtering-the-query" aria-hidden="true" class="aal_anchor" id="filtering-the-query"><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>Filtering the query</h3>



<p>The above would work for the simpler cases where the query only selects data available on both the gateway and the service. However, it’s not always the case. The underlying service schema doesn’t have <code>id</code> fields that <code>Node</code> interface has. In addition, one can only spread the fragment with compatible types: when both <code>User</code> and <code>Blog</code> fragments are spread inside the query, it will fail.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># Source query

{
  node(id: &quot;test-global-id&quot;) {
    id # Does not exist on User or Blog in original schemas
    ... on User { # Only valid in userById 
      username
    }
    ... on Blog { # Only valid in blogById
      title
    }    
  }
}</code></pre>



<p>To fix this, the delegation must filter out the incompatible fields and fragments, as well as unused fragments and variables after filter. Of course, you can do it by going through the document manually, tracking down the types and removing all the fields that don’t exist on the original schema. But you don’t have to because there is a&nbsp;<code>delegateToSchema</code>&nbsp;function inside&nbsp;<code>graphql-tools</code>&nbsp;that can do all that work for you.</p>



<p><em>Schema delegation is adapting the source query so that it matches the subschema automatically.</em></p>



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



<p><code>delegateToSchema</code>&nbsp;creates a GraphQL query that’s a valid query for an underlying schema and executes it. It accepts an object of options:</p>



<ul class="wp-block-list"><li><code>schema</code>&nbsp;is the sub-schema that should handle the delegated query</li><li><code>operation</code>&nbsp;is either&nbsp;<code>&quot;query&quot;</code>,&nbsp;<code>&quot;mutation&quot;</code>&nbsp;or&nbsp;<code>&quot;subscription&quot;</code>&nbsp;and determines the operation of the GraphQL document</li><li><code>fieldName</code>&nbsp;is the root field in the schema from which the query will start</li><li><code>args</code>&nbsp;is an object of&nbsp;<em>additional</em>&nbsp;arguments to pass to the field. These arguments supplement and/or override arguments given to the original field in the parent schema</li><li><code>context</code>&nbsp;is the GraphQL context for the execution</li><li><code>info</code>&nbsp;is&nbsp;<code>GraphQLResolveInfo</code>. It’s used to extract the selection set of the current query, along with variables and fragments.</li><li><code>transforms</code>&nbsp;is an array of GraphQL Schema Transforms. Transforms will be covered in the next article.</li></ul>



<p>Gateway resolvers using <code>delegateToSchema</code> will look like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { delegateToSchema } from &#039;graphql-tools&#039;;

const resolvers = {
  Query: {
    userById(parent, { id }, context, info) {
      const { type, localId } = deserializeGlobalId(id);
      return delegateToSchema({
        schema: subserviceSchema,
        operation: &#039;query&#039;,
        fieldName: &#039;userById&#039;,
        args: { id: localId },
        context,
        info,
       });
    },
    
    node(parent, { id }, context, info) {
      const { type, localId } = deserializeGlobalId(id);
      let fieldName;
      if (type === &#039;Blog&#039;) {
        fieldName = &#039;blogById&#039;,
      } else if (type === &#039;User&#039;) {
        fieldName = &#039;userById&#039;,
      } else {
        throw new Error(&#039;Invalid global id&#039;);
      }
      return delegateToSchema({
        schema: subserviceSchema,
        operation: &#039;query&#039;,
        fieldName,
        args: { id: localId },
        context,
        info,       
       });
    },
  },
};</code></pre>



<p>Here is how a <code>node</code> query would delegate to the service:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># Query coming to gateway

query(
  $id: ID! # overriden in parameters, so it won&#039;t be included
) {
  node(id: $id) { # delegate to userById
    # This is a selection set from the node resolver
    id # This field doesn&#039;t exist in User
    ...BlogFragment # Blog can&#039;t be spread here
    ...UserFragment
  }
}

# This fragment is used, so should be included
fragment UserFragment on User {
  username
}

# This fragment isn&#039;t used, so should be removed
fragment BlogFragment on Blog {
  title
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># Query sent to service

query(
  $_v0_id: ID! # generated variable name
) {
  userById(id: $_v0_id) {
    ...UserFragment
  }
}

fragment UserFragment on User {
  username
}</code></pre>



<p>Besides forwarding from root fields, you can use&nbsp;<code>delegateToSchema</code>&nbsp;to delegate from any other resolvers. For example, if you split&nbsp;<code>User</code>&nbsp;and&nbsp;<code>Blog</code>&nbsp;types to separate services, you would no longer be able to directly get&nbsp;<code>User.blogs</code>&nbsp;from User service and&nbsp;<code>Blog.user</code>&nbsp;from Blog service. However, you can connect them at the gateway server and use delegation to get related data:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="600" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Vel0AL9VsX9KmapLqC5QRw-1024x600.png" alt="" class="wp-image-808" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Vel0AL9VsX9KmapLqC5QRw-1024x600.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Vel0AL9VsX9KmapLqC5QRw-300x176.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Vel0AL9VsX9KmapLqC5QRw-768x450.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Vel0AL9VsX9KmapLqC5QRw-1200x703.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Vel0AL9VsX9KmapLqC5QRw.png 1250w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Get the code&nbsp;<a href="https://gist.github.com/freiksenet/e239464b56203ab79f5e5b5aa50de648#file-resolvers2-js" target="_blank" rel="noreferrer noopener">in a Gist</a></figcaption></figure>



<h2 class="wp-block-heading" id="4552"><a href="#schema-stitching-and-delegation" aria-hidden="true" class="aal_anchor" id="schema-stitching-and-delegation"><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 stitching and delegation</h2>



<p>Schema delegation is often used together with schema stitching. Schema stitching is a process of combining multiple GraphQL schemas together. It simplifies the creation of a gateway schema — especially when there are multiple services. Schema stitching automatically sets up delegation for root fields that already exist in the stitched-together schemas. New root fields (as well as any new non-root fields) require new resolvers. The above gateway schema can be created as follows:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">import { mergeSchemas, delegateToSchema } from &#039;graphql-tools&#039;;

const extensionSchema = `
  interface Node {
    id: ID!
  }
  extend type User implements Node {
    id: ID!
  }
  extend type Blog implements Node {
    id: ID!
  }
  extend type Query {
    node(id: ID!): Node
  }
`;

const schema = mergeSchemas({
  schemas: [serviceSchema, extensionSchema],
  resolvers: {
    Query: {
      node(parent, { id }, context, info) {
        const { type, localId } = deserializeGlobalId(id);
        let fieldName;
        if (type === &#039;Blog&#039;) {
          fieldName = &#039;blogById&#039;,
        } else if (type === &#039;User&#039;) {
          fieldName = &#039;userById&#039;,
        } else {
          throw new Error(&#039;Invalid global id&#039;);
        }
        return delegateToSchema({
          schema: serviceSchema,
          operation: &#039;query&#039;,
          fieldName,
          args: { id: localId },
          context,
          info,       
         });
      },
    },
    // ... more resolvers
 },
});</code></pre>



<p>You can read about schema stitching in more detail in&nbsp;<a href="https://www.apollographql.com/docs/graphql-tools/schema-stitching.html" target="_blank" rel="noreferrer noopener">the official docs</a>.</p>



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



<p>In my next article, I’ll tell how you can customize schema delegation with transforms. Even if your schema has been significantly altered using schema transforms, its ability to delegate to the subschema will be preserved.</p>



<p>Updated schema delegation and schema transforms are are going to be available in version 3 of&nbsp;<code>graphql-tools</code>&nbsp;and are already available as&nbsp;<code>graphql-tools@next</code>&nbsp;on npm — though please be aware that the exact API could still change slightly before the final release. Check out the PR on GitHub for the code:<a href="https://github.com/apollographql/graphql-tools/pull/527" target="_blank" rel="noreferrer noopener">Schema transforms, new mergeSchemas and everything by freiksenet · Pull Request #527 ·…This is out of date ATM, will be updatedgithub.com</a></p>



<p>If you’d like to read more about GraphQL schema delegation, check out these resources:</p>



<ul class="wp-block-list"><li><a href="https://github.com/apollographql/graphql-tools/blob/next-api/docs/source/schema-delegation.md" target="_blank" rel="noreferrer noopener">Official docs</a></li><li><a href="https://blog.graph.cool/graphql-schema-stitching-explained-schema-delegation-4c6caf468405" target="_blank" rel="noreferrer noopener">GraphQL Schema Stitching Explained</a>&nbsp;by Graphcool</li><li><a href="https://github.com/graphql-binding/graphql-binding" target="_blank" rel="noreferrer noopener">GraphQL Bindings docs</a>. GraphQL Bindings is a nice abstraction on top of schema delegation, which exposes a programmatic API to root fields of a schema.</li></ul>


GraphQL schema delegation


<p>With GraphQL you can query exactly what you want whenever you want. That is amazing for working with an API, but also has complex security implications. Instead of asking for legitimate, useful data, a malicious actor could submit an expensive, nested query to overload your server, database, network, or all of these. Without the right protections you open yourself up to a DoS (Denial of Service) attack.</p>



<p>For example, in our GraphQL API at&nbsp;<a rel="noreferrer noopener" href="https://spectrum.chat/" target="_blank">Spectrum</a>&nbsp;we have a relationship like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Thread {
  messages(first: Int, after: String): [Message]
}

type Message {
  thread: Thread
}

type Query {
  thread(id: ID!): Thread
}</code></pre>



<p>As you can see, you can query both the messages of a thread or the thread of a message. This circular relationship allows a bad actor to construct an expensive nested query like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query maliciousQuery {
  thread(id: &quot;some-id&quot;) {
    messages(first: 99999) {
      thread {
        messages(first: 99999) {
          thread {
            messages(first: 99999) {
              thread {
                # ...repeat times 10000...
              }
            }
          }
        }
      }
    }
  }
}</code></pre>



<p>Letting this kind of query through is very bad, since it exponentially increases the amount of objects loaded and will crash your entire server. While there are certain mitigations at other layers which make sending the query in the first place a bit harder (e.g. CORS), they can’t fully prevent it from happening.</p>



<h2 class="wp-block-heading" id="2031"><a href="#size-limiting" aria-hidden="true" class="aal_anchor" id="size-limiting"><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>Size Limiting</h2>



<p>A first, naïve approach we considered was to limit the incoming query size by raw bytes. Since the query is sent as a string, a quick length check would suffice:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">app.use(&#039;*&#039;, (req, res, next) =&gt; {
  const query = req.query.query || req.body.query || &#039;&#039;;
  if (query.length &gt; 2000) {
    throw new Error(&#039;Query too large&#039;);
  }
  next();
});</code></pre>



<p>Unfortunately, that doesn’t work very well in the real world: the check might allow nasty queries using short field names or block legitimate queries using long field names or nested fragments.</p>



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



<p>A second approach we considered was to have a whitelist of approved queries we use in our own application, and telling the server to not let any query pass except for those.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">app.use(&#039;/api&#039;, graphqlServer((req, res) =&gt; {
  const query = req.query.query || req.body.query;
  // TODO: Get whitelist somehow
  if (!whitelist[query]) {
    throw new Error(&#039;Query is not in whitelist.&#039;);
  }
  /* ... */
}));</code></pre>



<p>Maintaining that list of approved queries manually would obviously be a pain, but thankfully the Apollo team created&nbsp;<a rel="noreferrer noopener" href="https://github.com/apollographql/persistgraphql" target="_blank">persistgraphql</a>, which automatically extracts all queries from your client-side code and generates a nice JSON file out of it.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;scripts&quot;: {
    &quot;postbuild&quot;: &quot;persistgraphql src api/query-whitelist.json&quot;
  }
}</code></pre>



<p>This technique works beautifully and will block all vicious queries reliably. Unfortunately, it also has two major tradeoffs:</p>



<ol class="wp-block-list">
<li><strong>We can never change or delete queries, only add new ones</strong><strong>:</strong>&nbsp;if any user is running an outdated client we can’t just block their request. We’d likely have to keep a history of all queries ever used in production which is a lot more complex.</li>



<li><strong>We cannot open our API to the public:</strong>&nbsp;sometime in the future we’d like to open up our API to the public so that other developers can build their interpretation of what the Spectrum interface could look like. If we only let a whitelist of queries through that severely limits their options already and defeats the point of having a GraphQL API (super flexible system restrained by a synthetic whitelist).</li>
</ol>



<p>Those were constraints we couldn’t work with, so we went back to the drawing board.</p>



<h2 class="wp-block-heading" id="66f5"><a href="#depth-limiting" aria-hidden="true" class="aal_anchor" id="depth-limiting"><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>Depth Limiting</h2>



<p>One harmful aspect of the malicious query above is the nesting, classified by its&nbsp;<em>depth</em>, which makes the query exponentially more expensive. Each layer adds a lot more work for your backend, which can quickly add up when combined with lists.</p>



<p>We looked around and found&nbsp;<a rel="noreferrer noopener" href="https://github.com/stems/graphql-depth-limit" target="_blank">graphql-depth-limit</a>, a lovely module by&nbsp;<a rel="noreferrer noopener" href="https://twitter.com/acarl005" target="_blank">Andrew Carlson</a>, which enables us to easily limit the maximum depth of incoming queries. We checked our client and the deepest query we use has 7 levels, so we went with a (quite lenient) maximum depth of 10 and added it to our validation rules:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">app.use(&#039;/api&#039;, graphqlServer({
  validationRules: [depthLimit(10)]
}));</code></pre>



<p>That’s how simple depth limiting is!</p>



<h2 class="wp-block-heading" id="1a60"><a href="#amount-limiting" aria-hidden="true" class="aal_anchor" id="amount-limiting"><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>Amount Limiting</h2>



<p>The second harmful aspect of the query above is fetching 99999 of an object. No matter what that object is, fetching a ton of it will always be expensive. (Although the database stress might be mitigated by DataLoader, the network and processing stress won’t)</p>



<p>Instead of setting the type of the first argument to Int (which allows any arbitrary number) we have a custom scalar created with&nbsp;<a rel="noreferrer noopener" href="https://github.com/joonhocho/graphql-input-number" target="_blank">graphql-input-number</a>, that restricts the maximum value to 100:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const PaginationAmount = GraphQLInputInt({
  name: &#039;PaginationAmount&#039;,
  min: 1,
  max: 100,
});</code></pre>



<p>This will throw an error, if anybody queries for more than 100 objects. We then use that across our API anywhere we have a connection:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Thread {
  messages(first: PaginationAmount, after: String): [Message]
}</code></pre>



<p>Now we’ve entirely prevented the malicious query from above! 🎉</p>



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



<p>Unfortunately, there’s still a potential to overwhelm the server under the right conditions: there are certain app-specific queries that are neither too deep nor request too many objects but are still very expensive. For us at Spectrum, such a query could look like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query evilQuery {
  thread(id: &quot;54887141-57a9-4386-807c-ed950c4d5132&quot;) {
    messageConnection(first: 100) { ... }
    participants(first: 100) {
      threadConnection(first: 100) { ... }
      communityConnection { ... }
      channelConnection { ... }
      everything(first: 100) { ... }
    }
  }
}</code></pre>



<p>Neither the depth nor the individual amounts are exceptionally high in this query, so it would pass through our current protections. Yet, it potentially fetches tens of thousands of records, meaning it’s intensive on the database, server and network, a worst-case scenario.</p>



<p>To prevent this we would need to analyze queries before we run them to calculate their complexity and block them if were too expensive. While this is more work than both of our previous protections, it’ll make 100% sure no malicious query can get to our resolvers.</p>



<p><strong>Before you go ahead and spend a ton of time implementing query cost analysis be certain you need it.</strong>&nbsp;Try to crash or slow down your staging API with a nasty query and see how far you get — maybe your API doesn’t have these kinds of nested relationships, or maybe it can handle fetching thousands of records at a time perfectly fine and doesn’t need query cost analysis!</p>



<p>I ran the above query locally on my maxed-out 2017 MacBook Pro and it took our API server a good 10–15 seconds to respond with a megabyte of JSON. We really need it since we never want anybody bombarding our API with that. (<a href="https://developer.github.com/v4/guides/resource-limitations/" target="_blank" rel="noreferrer noopener">The GitHub GraphQL API also uses Query Cost Analysis</a>)</p>



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



<p>There are a couple of packages on npm to implement query cost analysis. Our two front-runners were&nbsp;<a href="https://github.com/4Catalyzer/graphql-validation-complexity" target="_blank" rel="noreferrer noopener">graphql-validation-complexity</a>, a plug-n-play module, or&nbsp;<a href="https://github.com/pa-bru/graphql-cost-analysis" target="_blank" rel="noreferrer noopener">graphql-cost-analysis</a>, which gives you more control by letting you specify a @cost directive. There’s also&nbsp;<a href="https://github.com/ivome/graphql-query-complexity" target="_blank" rel="noreferrer noopener">graphql-query-complexity</a>, but I wouldn’t recommend choosing it over graphql-cost-analysis since it’s the same idea without directive or multiplier support.</p>



<p>We went with&nbsp;<a href="https://github.com/pa-bru/graphql-cost-analysis" target="_blank" rel="noreferrer noopener">graphql-cost-analysis</a>&nbsp;because we have a large discrepancy between our fastest resolvers (20μs) and our slowest ones (10s+), so we needed the control we got from it. That being said, maybe graphql-validation-complexity is enough for you, try it out for sure!</p>



<p>The way it works is that you specify the relative cost of resolving a certain field or type. It also has multiplication support, so if you requested a list any nested field within would be multiplied by the pagination amount, which is very neat.</p>



<p>This is what the @cost directive looks like in practice:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Participant {
  # The complexity of getting one thread in a thread connection is 3, and multiply that by the amount of threads fetched
  threadConnection(first: PaginationAmount, after: String): ThreadConnection @cost(complexity: 3, multipliers: [&quot;first&quot;])
}

type Thread {
  author: Author @cost(complexity: 1)
  participants(first: PaginationAmount,...): [Participant] @cost(complexity: 2, multipliers: [&quot;first&quot;])
}</code></pre>



<p>This is just a snippet of our API types, but you get the point. You specify how complex a certain field is, which argument to multiply by and the maximum cost and graphql-cost-analysis does the rest for you.</p>



<p>I determined how complex certain resolvers are via the performance tracking data exposed by <a href="https://studio.apollographql.com/signup?referrer=blog">Apollo Studio</a>. I went through the entire schema and assigned a value based on the p99 service time. Then we looked through all the queries on our client to figure out the most expensive one, which got ~500 complexity points. To give us a bit of leeway for the future we set the maximum complexity to 750.</p>



<p>Running the evilQuery from above, now that we’ve added graphql-cost-analysis, I get an error message telling me that the “GraphQL query exceeds maximum complexity, please remove some nesting or fields and try again. (max: 750, actual: 1010319)”</p>



<p><strong>1 million complexity points? Rejected!</strong></p>



<h2 class="wp-block-heading" id="c620"><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>To summarize, I’d recommend using Depth and Amount Limiting as the minimum protection for any GraphQL API — they’re easy to implement and will give ample safety. Depending on your specific security requirements and schema, you might also want to investigate Query Cost Analysis. While it is a bit more work than the other tools, it does provide full coverage in the defense against malicious actors.</p>



<hr class="wp-block-separator has-css-opacity"/>



<p><a href="https://spectrum.chat/thread/dc17eab7-fe14-44de-967b-79d5e6ab6e6a" target="_blank" rel="noreferrer noopener"><em>Discuss this post in the GraphQL community on Spectrum</em></a></p>


Securing Your GraphQL API from Malicious Queries


<p>Over the holiday break, while the in-laws slept soundly and not a child was making a peep, I had the chance to play around with&nbsp;<a href="https://reasonml.github.io/" target="_blank" rel="noreferrer noopener">ReasonML</a>. Reason is a new programming language built on top of OCaml and designed to be compiled into JavaScript. After spending a couple of years with TypeScript over the development of Apollo, I thought it would be fun to try another compile to JavaScript language.</p>



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



<p>There are a&nbsp;<a href="https://reasonml.github.io/guide/what-and-why" target="_blank" rel="noreferrer noopener">lot of benefits</a>&nbsp;to choosing a language like Reason, but honestly I just wanted to try it out to see what all the excitement is about! After Cheng Lou’s talk at&nbsp;<a href="https://www.youtube.com/watch?v=_0T5OSSzxms" target="_blank" rel="noreferrer noopener">React Conf in 2017</a>&nbsp;I wanted to see for myself if it was an exciting, but shiny new toy, or if it could make a big difference in how we write and ship JavaScript.</p>



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



<p>I only had a few hours to play around with a project so I opted to rebuild something I know quite well, a GraphQL endpoint! I choose to remodel the <a rel="noreferrer noopener" href="https://launchpad.graphql.com/1jzxrj179" target="_blank">Authors and Posts</a> example from Apollo Launchpad. If you haven’t checked it out before, now is the time! The app is less than 80 lines of JavaScript so how hard could it be to model in Reason?</p>



<figure class="wp-block-embed is-type-photo is-provider-giphy"><div class="wp-block-embed__wrapper">
<a href="https://giphy.com/gifs/nfl-football-xTgeJd2Z2b5OA0H7Ik"><img loading="lazy" decoding="async" src="https://media4.giphy.com/media/xTgeJd2Z2b5OA0H7Ik/giphy.gif" alt="Pittsburgh Steelers Football GIF by NFL - Find &amp; Share on GIPHY" width="480" height="270" /></a>
</div></figure>



<p>Getting started was pretty easy thanks to the excellent documentation at&nbsp;<a href="https://reasonml.github.io/" target="_blank" rel="noreferrer noopener">https://reasonml.github.io</a>. I quickly bootstrapped a project using&nbsp;<code>bsb -init authors-and-posts -theme basic-reason</code>&nbsp;and I was off to the races!</p>



<h3 class="wp-block-heading" id="87c3"><a href="#modules-everywhere" aria-hidden="true" class="aal_anchor" id="modules-everywhere"><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>Modules Everywhere</h3>



<p>The most jarring change for me as a JavaScript developer was the lack of explicit import definitions. In Reason, each module is available without manually requiring it and each file is converted into a module. Turns out this can be pretty great for GraphQL because you can easily model each type in its own module.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">open Data;

let typeDef = {|
  type Author {
    id: Int!
    firstName: String
    lastName: String
    posts: [Post] # the list of Posts by this author
  }
|};

type resolvers = {. &quot;posts&quot;: Js.Array.t(post)};

let resolvers = {
  &quot;posts&quot;: (author: Data.author) =&gt;
    Js.Array.filter((post) =&gt; post##authorId === author##id, posts)
};</code></pre>



<p>Did you notice the&nbsp;<code>open Data;</code>&nbsp;at the top of that file? It acts kinda like a JavaScript&nbsp;<code>import</code>&nbsp;but allows you to access any named export from that file without having to manually reference it. Variables like&nbsp;<code>post</code>&nbsp;and values like&nbsp;<code>posts</code>&nbsp;are actually coming from the&nbsp;<code>Data</code>&nbsp;module! I left the&nbsp;<code>Data.author</code>&nbsp;to show that you can still use the module reference which can make the code easier to understand.</p>



<p>Defining types also shows where graphql-tools shines for building GraphQL schemas. Looking at this file, it is super easy to know what is being built and the default resolver from GraphQL means I only need to figure out how to link an author and post together!</p>



<h3 class="wp-block-heading" id="474b"><a href="#immutable-by-design" aria-hidden="true" class="aal_anchor" id="immutable-by-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>Immutable by design</h3>



<p>At this point, everything is running super smoothly so surely something has to go wrong? Absolutely.</p>



<p>In the Authors and Posts example, we see there is some local data that is updated with a mutation:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">Mutation: {
  upvotePost: (_, { postId }) =&gt; {
    const post = find(posts, { id: postId });
    if (!post) {
      throw new Error(`Couldn&#039;t find post with id ${postId}`);
    }
    post.votes += 1;
    return post;
  },
},</code></pre>



<p>In Reason, when you are defining JavaScript objects, all of the fields are immutable by default. So trying to update the votes in the post will throw some errors in the console when you compile it. Luckily, there is a growing community of Reason developers in Discord that are happy to help! <a rel="noreferrer noopener" href="https://medium.com/u/516e71756f17?source=post_page-----ff877df60d2a----------------------" target="_blank">Yawar λmin</a> walked me through using <code>ref</code> to tell Reason that the <code>votes</code> field could be mutated in place. When defining a type, like on line 9, you pass the underlying mutable type, in this case int, to <code>ref</code> . When declaring data, like on line 12, you pass the initial value that can be mutated to the <code>ref</code> call. It’s a pretty cool way to be very specific about what can and cannot change in your data!</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">type author = {. &quot;id&quot;: int, &quot;firstName&quot;: string, &quot;lastName&quot;: string};

let authors = [|
  {&quot;id&quot;: 1, &quot;firstName&quot;: &quot;Tom&quot;, &quot;lastName&quot;: &quot;Coleman&quot;},
  {&quot;id&quot;: 2, &quot;firstName&quot;: &quot;Sashko&quot;, &quot;lastName&quot;: &quot;Stubailo&quot;},
  {&quot;id&quot;: 3, &quot;firstName&quot;: &quot;Mikhail&quot;, &quot;lastName&quot;: &quot;Novikov&quot;}
|];

type post = {. &quot;id&quot;: int, &quot;authorId&quot;: int, &quot;title&quot;: string, &quot;votes&quot;: ref(int)};

let posts = [|
  {&quot;id&quot;: 1, &quot;authorId&quot;: 1, &quot;title&quot;: &quot;Introduction to GraphQL&quot;, &quot;votes&quot;: ref(2)},
  {&quot;id&quot;: 2, &quot;authorId&quot;: 2, &quot;title&quot;: &quot;Welcome to Apollo&quot;, &quot;votes&quot;: ref(3)},
  {&quot;id&quot;: 3, &quot;authorId&quot;: 2, &quot;title&quot;: &quot;Advanced GraphQL&quot;, &quot;votes&quot;: ref(1)},
  {&quot;id&quot;: 4, &quot;authorId&quot;: 3, &quot;title&quot;: &quot;Launchpad is Cool&quot;, &quot;votes&quot;: ref(7)}
|];</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-">open Data;

let typeDef = {|
  type Mutation {
    upvotePost(postId: Int!): Post
  }
|};

type upvotePostArgument = {. &quot;postId&quot;: int};

type root;

type resolvers = {. &quot;upvotePost&quot;: (root, upvotePostArgument) =&gt; post};

exception MissingPost(string);

let resolvers: resolvers = {
  &quot;upvotePost&quot;: (_, filter) =&gt;
    switch (Js.Array.find((post) =&gt; post##id === filter##postId, posts)) {
    | None =&gt; raise(
      MissingPost(&quot;Couldn&#039;t find post with id &quot; ++ string_of_int(filter##postId))
    )
    | Some(p) =&gt;
      incr(p##votes);
      p
    }
};</code></pre>



<h3 class="wp-block-heading" id="2cc9"><a href="#putting-it-together" aria-hidden="true" class="aal_anchor" id="putting-it-together"><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>Putting it together</h3>



<p>At this point my egg nog was getting warm and I had re-watched&nbsp;<a href="https://medium.com/u/25b2696a8b5d?source=post_page-----ff877df60d2a----------------------" target="_blank" rel="noreferrer noopener">Brandon Dail</a>’s videos on building with Reason (<a href="https://www.youtube.com/watch?v=Yflk43afWj4" target="_blank" rel="noreferrer noopener">here&nbsp;</a>and&nbsp;<a href="https://www.youtube.com/watch?v=k77aR_JyvEE" target="_blank" rel="noreferrer noopener">here</a>) a couple times, I was ready to fire up an express app and try it out! I opted to write the express portion in JavaScript to save time and the&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/example.html" target="_blank" rel="noreferrer noopener">Apollo Server docs</a>&nbsp;are pretty much copy, paste, magic!</p>



<p>One of the coolest parts of Reason is its ability to compile into JavaScript using a tool called Bucklescript. By default, it will even place the generated JavaScript files right next to the Reason ones making it easy to understand what is happening under the hood, and so easy to use alongside existing JavaScript apps! All I had to do was import my schema from the generated JavaScript file and I had an app up and running!</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const express = require(&quot;express&quot;);
const bodyParser = require(&quot;body-parser&quot;);
const { graphqlExpress, graphiqlExpress } = require(&quot;apollo-server-express&quot;);

// import schema from generated bucklescript files
const { schema } = require(&quot;./src/Schema.bs.js&quot;);

// Initialize the app
const app = express();

const { PORT = 3000 } = process.env;
const endpointURL = `/`;

// The GraphQL endpoint
app.post(endpointURL, bodyParser.json(), graphqlExpress({ schema }));

// GraphiQL, a visual editor for queries
app.get(endpointURL, graphiqlExpress({ endpointURL }));

// Start the server
app.listen(PORT);</code></pre>



<h3 class="wp-block-heading" id="07eb"><a href="#deployment-with-up" aria-hidden="true" class="aal_anchor" id="deployment-with-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>Deployment with Up</h3>



<p>Now that I had this super cool little Reason and GraphQL app, I had to show it off! Luckily there is an incredible tool for setting up and deploying to AWS Lambda called <a rel="noreferrer noopener" href="https://github.com/apex/up" target="_blank">Up </a>by <a rel="noreferrer noopener" href="https://medium.com/u/bbb3c7ccb0a0?source=post_page-----ff877df60d2a----------------------" target="_blank">TJ Holowaychuk</a>. I setup my AWS credentials, bundled my app using browserify for node, and ran <code>up</code> in my console…</p>



<figure class="wp-block-embed is-type-photo is-provider-giphy"><div class="wp-block-embed__wrapper">
<a href="https://giphy.com/gifs/mrw-td-R8n7YlPHe34dy"><img loading="lazy" decoding="async" src="https://media0.giphy.com/media/R8n7YlPHe34dy/giphy.gif" alt="The Land Of Make Believe Wow GIF - Find &amp; Share on GIPHY" width="334" height="251" /></a>
</div></figure>



<p>In under a minute I had a working GraphQL app, built with Reason, running on AWS Lambda! You can check out the app in action&nbsp;<a href="https://rhi2j2y368.execute-api.us-east-1.amazonaws.com/development" target="_blank" rel="noreferrer noopener">here</a>&nbsp;and see the source code for it&nbsp;<a href="https://github.com/jbaxleyiii/authors-and-posts-reason" target="_blank" rel="noreferrer noopener">over here</a>.</p>



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



<p>I had a couple takeaways from this short, but fun, adventure into a new language. One is that the tooling for developers to learn and build products is absolutely incredible today. Auto formatting, strong editor integration, and helpful errors make a big difference in picking something up.</p>



<p>The other, and more important takeaway, is how important a community is to a project. Even as young as Reason and Up are, I was able to get help from people like&nbsp;<a href="https://medium.com/u/ecb657c8b22d?source=post_page-----ff877df60d2a----------------------" target="_blank" rel="noreferrer noopener">Jared Forsyth</a>&nbsp;and&nbsp;<a href="https://medium.com/u/bbb3c7ccb0a0?source=post_page-----ff877df60d2a----------------------" target="_blank" rel="noreferrer noopener">TJ Holowaychuk</a>&nbsp;when I ran into problems in almost no time. I’ve seen this time and time again in the Apollo community and in 2018 I hope that we all continue to explore and help each other as we build new things and try new ideas. Come find me in the Apollo Slack if you want to chat about GraphQL, Reason, or eating cookies for Santa while building an app.</p>


Exploring Reason and GraphQL


<p><em>This is a guest post by Dan Shapiro, Senior eCommerce Engineer at&nbsp;</em><a href="https://www.express.com/" target="_blank" rel="noreferrer noopener"><em>Express</em></a><em>.</em></p>



<p>As one of the biggest specialty retail brands in the world, Express keeps up with both fashion and technology trends. Keeping pace technologically means balancing innovation with performance and security. Overhauling the architecture behind the shopping experience’s key eCommerce pages for&nbsp;<a href="https://www.express.com/" target="_blank" rel="noreferrer noopener">Express.com</a>&nbsp;is no task to be taken lightly.</p>



<p>I’m part of the team building a new shopping architecture. Today, Express leverages Adobe Experience Manager (AEM) as the customer-facing experience layer powered by our proprietary APIs built on Oracle’s ATG Web Commerce engine. We wanted to upgrade to a more responsive stack for the website’s experience to be “faster and snappier,” while also being flexible enough to react to changing design trends and customer experience patterns. To meet this goal, we formed a new product development team steeped in Javascript, React, and GraphQL expertise and focused on the product page to introduce a new technical stack.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="452" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-1024x452.png" alt="" class="wp-image-927" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-1024x452.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-300x132.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-768x339.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-1536x677.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-2048x903.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-1200x529.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_q4LCxA-gY9bWsszbzM4KpQ-1980x873.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Product Page using our new architecture</figcaption></figure>



<p>We chose React as our foundational Javascript framework. Since more than 50% of our traffic is mobile, we selected GraphQL, which lets the client-side developer control how much data is flowing to the client. That optimization benefit alone was worth the integration. We considered other data orchestration engines, but GraphQL was selected as the best fit with our familiarity and general community acceptance and knowledge.</p>



<h2 class="wp-block-heading" id="7078"><a href="#discovering-apollo-server-and-client" aria-hidden="true" class="aal_anchor" id="discovering-apollo-server-and-client"><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>Discovering Apollo Server and Client</h2>



<p>Since&nbsp;<a href="https://github.com/graphql/graphql-js" target="_blank" rel="noreferrer noopener"><em>graphql-js</em></a>&nbsp;is the reference implementation for a GraphQL server, but isn’t built to scale, we needed a production-tolerant solution. Apollo was new to the team. During GraphQL proof-of-concepting, we decided to explore&nbsp;<a href="https://github.com/apollographql/apollo-server" target="_blank" rel="noreferrer noopener">Apollo Server</a>&nbsp;based on its reputation as being very developer friendly and production ready. Apollo Server adds numerous features on top of that reference implementation, such as error handling and easy-to-understand responses. After selecting Apollo’s GraphQL Server,&nbsp;<a href="https://github.com/apollographql/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;was an obvious choice. Elegant Apollo Client design choices (like the easy-to-use pagination model) made for a great developer experience as well as an efficient new tool in our tool-set.</p>



<h2 class="wp-block-heading" id="cfe2"><a href="#graphql-boosts-our-development-velocity" aria-hidden="true" class="aal_anchor" id="graphql-boosts-our-development-velocity"><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>GraphQL Boosts Our Development Velocity</h2>



<p>Now GraphQL helps us move faster in product development. We recently had a scenario calling for a new field to be added to a product response to determine the products category. Our API team estimated two weeks to complete the addition. By simply creating a new resolver, we added the new Boolean value, specifying whether the product ID was one of a special set of 25 products, to the response. Within thirty minutes, everyone who uses that API on our side had access to the new field, instead of it being hidden in a client-side module. We saved two weeks of development time.</p>



<h2 class="wp-block-heading" id="6936"><a href="#the-apollo-engine-advantage" aria-hidden="true" class="aal_anchor" id="the-apollo-engine-advantage"><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 Apollo Engine Advantage</h2>



<p>Early on in our POC we started using&nbsp;<a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;(previously Apollo Optics) to understand performance of our new stack. During this proof of concept, we wrote a query to get product data which had a large variance in running time. As product developers, Engine helped us understand our backend APIs’ impact on performance. In production we now had the ability to see all the data thanks to Engine. Now we could see all the calls coming to the website and deeper specific traffic data. From a monitoring perspective, we are complementing our traffic and conversion data. We now have a view of how the stack is handling traffic that has illustrated where we need optimization and has provided a more accurate view of scale of traffic and any potential issues.</p>



<p>We leverage Akamai to cache our GraphQL queries every 24 hours. Each product on page is seen by Engine once every 24 hours. In Engine we should see a maximum of around 5,000 products if it’s cached properly. However, in Engine we were seeing around 300,000 a day. This called out a caching challenge we are still researching.</p>



<p>Another challenge Engine helped identify was backend API return errors. We were alerted to a window of 20-second responses that our API team verified as 503s. Those errors were impacting customer experiences, but we were not aware of them. Once identified we adjusted our integration. In short, Engine has been instrumental in identifying issues across our product architecture to improve the end user experience. It has given us confidence in the entire stack.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="450" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-1024x450.png" alt="" class="wp-image-926" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-1024x450.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-300x132.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-768x338.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-1536x675.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-2048x901.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-1200x528.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_roaRYVcn1L-SRPvKccZiTA-1980x871.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Shopping Bag page using our new architecture</figcaption></figure>



<p>Next up, we are extending this stack further down the conversion funnel into the shopping bag and check out experiences. With React and GraphQL monitored by Apollo Engine, we are confident we will be delivering a fast, accessible customer experience<strong>.</strong></p>


Changing the architecture of Express.com

The GraphQL stack: How everything fits together


<p>Today, we are proud to release&nbsp;<code>graphql-tools</code>&nbsp;2.0, the first stable release of a new feature we call “schema stitching”: the ability to create a single GraphQL schema from multiple underlying GraphQL APIs. We think this new approach to schema development will unlock a lot of new potential in GraphQL, and we&#8217;re very eager to see what people can do with it.</p>



<p><a href="http://dev.apollodata.com/tools/graphql-tools/schema-stitching.html" target="_blank" rel="noreferrer noopener">Learn how to use schema stitching in the docs!</a></p>



<p><em>Thanks to&nbsp;</em><a href="https://medium.com/u/803918030a60?source=post_page-----8944064904a5----------------------" target="_blank" rel="noreferrer noopener"><em>Sashko Stubailo</em></a><em>&nbsp;for co-authoring this post.</em></p>



<h3 class="wp-block-heading" id="c45f"><a href="#what-is-graphql-tools" aria-hidden="true" class="aal_anchor" id="what-is-graphql-tools"><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 graphql-tools?</h3>



<p><code>graphql-tools</code>&nbsp;is actually the oldest library developed and maintained by the Apollo community. It started out as a toolbox of several functions related to GraphQL schema development, but today it&#8217;s the&nbsp;<a href="https://npm-stat.com/charts.html?package=graphql-tools&amp;package=graphql&amp;from=2016-10-02&amp;to=2017-10-02" target="_blank" rel="noreferrer noopener">most popular</a>&nbsp;library for creating and manipulating GraphQL schemas in JavaScript, aside from the GraphQL.js reference implementation it&#8217;s based on. It was the first library to pioneer the&nbsp;<a href="http://dev.apollodata.com/tools/graphql-tools/index.html" target="_blank" rel="noreferrer noopener">GraphQL-first approach</a>&nbsp;of developing a GraphQL server by starting from a GraphQL schema definition string.</p>



<p>We are excited to see&nbsp;<code>graphql-tools</code>&nbsp;continue to drive innovative new ways to develop GraphQL schemas with the introduction of the new schema stitching feature in 2.0.</p>



<h2 class="wp-block-heading" id="055d"><a href="#the-case-for-schema-stitching" aria-hidden="true" class="aal_anchor" id="the-case-for-schema-stitching"><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 case for schema stitching</h2>



<p>One of the main benefits of GraphQL is that you can query all of your data as part of one schema and get everything you need in one request. But as your schema grows, it might become cumbersome to manage it all as one codebase, and it starts to make sense to split it into parts. This separation can be both logical (split schemas into different modules in a codebase) as well as physical (schemas split between different services).</p>



<p>Plus, GraphQL is frequently used as an API gateway on top of REST APIs or other kinds of microservices. So it feels like you should get some big benefits if your backends are themselves implemented with GraphQL. Unfortunately, until now you didn’t — it was just as hard or harder to put a GraphQL gateway over multiple GraphQL services. Another similar idea is to combine multiple 3rd party APIs together with some local data, to create a mash-up GraphQL gateway.</p>



<h2 class="wp-block-heading" id="0599"><a href="#schema-stitching-in-the-wild" aria-hidden="true" class="aal_anchor" id="schema-stitching-in-the-wild"><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 stitching in the wild</h2>



<p>One of our favorite aspects of the open source development and design process is getting feedback as soon as possible. So even during the earliest design phases of this new feature we were excited to learn as much as possible about the use cases involved in schema stitching.</p>



<p>Here’s what&nbsp;<a href="https://medium.com/u/6a98eb806571?source=post_page-----8944064904a5----------------------" target="_blank" rel="noreferrer noopener">Jason Lengstorf</a>&nbsp;said about a GraphQL system he designed at IBM:</p>



<p><em>We needed a way to let multiple teams create, test, and maintain GraphQL data sources in isolation, but ultimately expose them all as part of the same&nbsp;</em><code>&lt;em&gt;/graphql&lt;/em&gt;</code><em>&nbsp;endpoint on our platform.</em></p>



<p>And&nbsp;<a href="https://medium.com/u/6d7ee7c0b225?source=post_page-----8944064904a5----------------------" target="_blank" rel="noreferrer noopener">Abhi Aiyer</a>&nbsp;from Workpop said this about their server:</p>



<p><em>At Workpop our goal is to deconstruct our monolithic Meteor application into a set of microservices. When thinking about how our clients would interact with these services, GraphQL was a natural choice to provide a great query language for the data these services own. Thus, we set out to work on a solution that would combine our graphql services into one schema. This allows the client to query APIs across the system without worrying about the address of any given downstream service.</em></p>



<p>Here’s how startup founder&nbsp;<a href="https://medium.com/u/eedd44bc61fe?source=post_page-----8944064904a5----------------------" target="_blank" rel="noreferrer noopener">Devan Beitel</a>&nbsp;explained building an API that combines local data with Yelp:</p>



<p><em>We are using the graphql-tools beta to stitch together two external services, Yelp and Graphcool.</em><em>&nbsp;A query is sent to the Yelp API, and the response is a list of businesses. When that list is returned the ID is used as a query parameter sent to Graphcool. Graphcool returns any user specified data like if the business is operating and what hours it is open. Finally, the Yelp and Graphcool data is stitched together and returned to our React Native app.</em></p>



<p>Armed with this conversations with hundreds of GraphQL developers like these, we were sure that schema stitching could be a huge boost in how GraphQL schemas are developed, and had a lot of information about the diversity of needs and use cases. For more information, check out&nbsp;<a href="https://dev-blog.apollodata.com/graphql-schema-stitching-8af23354ac37" target="_blank" rel="noreferrer noopener">our previous post about schema stitching</a>.</p>



<h2 class="wp-block-heading" id="5ae1"><a href="#the-graphql-tools-schema-stitching-design" aria-hidden="true" class="aal_anchor" id="the-graphql-tools-schema-stitching-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>The&nbsp;<code>graphql-tools</code>&nbsp;schema stitching design</h2>



<p>Initially, we viewed local code modularization and remote schema merging as separate situations, but it turns out that they are very similar. As a result, we came up with the&nbsp;<code>makeRemoteExecutableSchema</code>&nbsp;function that is very similar to the&nbsp;<code>makeExecutableSchema</code>&nbsp;function already present in&nbsp;<code>graphql-tools</code>. It produces a GraphQL schema instance from any remote GraphQL API using built-in GraphQL introspection. This way, we can write a schema stitching function that just operates on a local schema instance and avoid treating the local and remote cases separately.</p>



<p>The actual&nbsp;<code>mergeSchemas</code>&nbsp;function that implements the stitching, in its basic use case, just accepts list of schemas and produces a new schema that merges together all of the types and the Query and Mutation fields from each. That schema can then be queried as if it were just one schema, and handles delegating different parts of the query to the correct backend.</p>



<h3 class="wp-block-heading" id="7409"><a href="#links-and-conflicts" aria-hidden="true" class="aal_anchor" id="links-and-conflicts"><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>Links and conflicts</h3>



<p>Two additional features are avaliable with&nbsp;<code>mergeSchemas</code>: schema extensions and conflict resolution. First, it&#8217;s possible to link between any two types in your new schema (even across backends) by extending the schema and passing the custom&nbsp;<code>resolvers</code>&nbsp;option:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="1014" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_rJLg3vm8e4HXJCGBP90n3g-1024x1014.png" alt="" class="wp-image-969" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_rJLg3vm8e4HXJCGBP90n3g-1024x1014.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rJLg3vm8e4HXJCGBP90n3g-300x297.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rJLg3vm8e4HXJCGBP90n3g-150x150.png 150w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rJLg3vm8e4HXJCGBP90n3g-768x761.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rJLg3vm8e4HXJCGBP90n3g.png 1058w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Second, you can manage conflicts between types with the&nbsp;<code>onTypeConflict</code>&nbsp;callback.&nbsp;<code>onTypeConflict</code>&nbsp;is very useful when using common types across multiple APIs. Normally, if a type with the same name appears in two schemas, they will cause type conflicts. With&nbsp;<code>onTypeConflict</code>, one can define custom logic to resolve that overlap, for example by using the first type of those two or merging them in some way.</p>



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



<p>If you want to jump right in and see this new feature in action, we’ve got two complete examples on&nbsp;<a href="http://launchpad.graphql.com/" target="_blank" rel="noreferrer noopener">Launchpad</a>. The first one uses two very simple schemas, one to describe a simple user system:</p>



<pre class="wp-block-preformatted">type User {<br>  id: ID!<br>  email: String<br>}type Query {<br>  userById(id: ID!): User<br>}</pre>



<p>Then, there’s a simple schema for “Chirps”: small text snippets that can be posted by an author:</p>



<pre class="wp-block-preformatted">type Chirp {<br>  id: ID!<br>  text: String<br>  authorId: ID!<br>}type Query {<br>  chirpById(id: ID!): Chirp<br>  chirpsByAuthorId(authorId: ID!): [Chirp]<br>}</pre>



<p>With just a few lines of code, we can merge them together:</p>



<pre class="wp-block-preformatted">export const schema = mergeSchemas({<br>  schemas: [chirpSchema, authorSchema],<br>});</pre>



<p>For the complete code, as well as an example of how to add resolvers between these types, see the example on Launchpad:<a href="https://launchpad.graphql.com/8r11mk9jq" target="_blank" rel="noreferrer noopener">Apollo LaunchpadView this code sample on Launchpad, the GraphQL server playground.launchpad.graphql.com</a></p>



<p>We also have a more complex example with a real estate theme, which combines a&nbsp;<a href="https://launchpad.graphql.com/v7l45qkw3" target="_blank" rel="noreferrer noopener">property schema</a>&nbsp;with a&nbsp;<a href="https://launchpad.graphql.com/41p4j4309" target="_blank" rel="noreferrer noopener">booking schema</a>&nbsp;into a larger&nbsp;<a href="https://launchpad.graphql.com/q5kq9z15p" target="_blank" rel="noreferrer noopener">merged schema</a>.</p>



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



<p>This is the first stable release of this feature, so we focused on creating an API that is generic but also simple to use. However, we are sure that there are more possible extension points to merging schemas, as well as opportunities to make the API more declarative for common cases.</p>



<p>For now we’re excited to see more use cases and approaches from the community, and we can improve the API in the future to work better with those cases.</p>



<h3 class="wp-block-heading" id="fa9c"><a href="#join-the-discussion" aria-hidden="true" class="aal_anchor" id="join-the-discussion"><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>Join the discussion</h3>



<p>If you’d like to share your schema stitching use case or give us feedback on this feature, let us know in the the&nbsp;<strong>#schema-stitching</strong>&nbsp;channel on&nbsp;<a href="http://apollodata.com/#slack" target="_blank" rel="noreferrer noopener">Apollo Slack</a>.</p>



<p>The team and contributors who have been working on schema stitching in graphql-tools will be attending and speaking at GraphQL Summit 2017, October 25–26 in San Francisco, along with GraphQL engineers from GitHub, Facebook, Twitter, Twitch, Yelp, and more. Use the discount code&nbsp;<code>APOLLOBFF</code>&nbsp;for 20% off your ticket if you’d like to join.</p>


GraphQL-Tools 2.0 with Schema Stitching

GraphQL schema stitching


<p>Today, after more than a year of development, testing and production use, we’re proud to announce the 1.0 release of&nbsp;<a href="https://github.com/apollographql/apollo-server" target="_blank" rel="noreferrer noopener">Apollo Server</a>!&nbsp;🎉</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Late edit: We also just announced&nbsp;<a href="https://dev-blog.apollodata.com/apollo-optics-is-now-free-up-to-1-million-graphql-requests-a-month-d759248ea084" target="_blank" rel="noreferrer noopener">Apollo Optics is now free for most apps</a>, up to 1 million queries per month!&nbsp;<a href="http://apollodata.com/optics" target="_blank" rel="noreferrer noopener">Try out Optics</a>&nbsp;to visualize, monitor, and track your GraphQL API.</p></blockquote>



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



<p>Apollo Server is a community-maintained, open-source GraphQL server. It works with all Node.js HTTP server frameworks: Express, Connect, Hapi, Koa, AWS Lambda, Restify and Micro. It is built on top of the&nbsp;<code>&lt;a href=&quot;https://github.com/graphql/graphql-js&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql-js&lt;/a&gt;</code>&nbsp;reference implementation.</p>



<p>Apollo Server is built with the following principles in mind:</p>



<ul class="wp-block-list"><li><strong>By the community, for the community</strong>: Apollo Server’s development is driven by the needs of developers.</li><li><strong>Simplicity</strong>: by keeping things simple, Apollo Server is easier to use, easier to contribute to, and more secure.</li><li><strong>Performance</strong>: Apollo Server is well-tested and production-ready — no modifications needed.</li></ul>



<p>Those were the principles that we laid out when the project started, and I’m happy to see that the principles still hold today.</p>



<h2 class="wp-block-heading" id="2668"><a href="#zero-to-4k" aria-hidden="true" class="aal_anchor" id="zero-to-4k"><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>Zero to 4K</h2>



<p>The development of Apollo Server has been driven by the community from the very beginning, and it’s been really exciting to watch. In a little more than a year, it went from zero to&nbsp;<a href="https://github.com/apollographql/graphql-server/graphs/contributors" target="_blank" rel="noreferrer noopener">over 600 commits by 45 contributors</a>, and NPM downloads have grown to&nbsp;<a href="https://npm-stat.com/charts.html?package=graphql-server-core&amp;from=2016-10-01&amp;to=2017-09-30" target="_blank" rel="noreferrer noopener">almost 4K per day</a>!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="618" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_i8oWDQC2A0RGES55yi-ZXg-1024x618.png" alt="" class="wp-image-1043" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_i8oWDQC2A0RGES55yi-ZXg-1024x618.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_i8oWDQC2A0RGES55yi-ZXg-300x181.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_i8oWDQC2A0RGES55yi-ZXg-768x463.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_i8oWDQC2A0RGES55yi-ZXg-1200x724.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_i8oWDQC2A0RGES55yi-ZXg.png 1286w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>NPM downloads for Apollo Server</figcaption></figure>



<p>Among the production users, there are a couple of names that you might recognize:</p>



<ul class="wp-block-list"><li><a href="https://www.creditkarma.com/auth/logon/" target="_blank" rel="noreferrer noopener">Credit Karma</a></li><li><a href="http://www.ticketmaster.com/" target="_blank" rel="noreferrer noopener">Ticketmaster</a></li><li><a href="https://www.opentable.com/" target="_blank" rel="noreferrer noopener">OpenTable</a></li><li><a href="https://coralproject.net/" target="_blank" rel="noreferrer noopener">Mozilla’s Coral project</a>&nbsp;(with NYTimes &amp; Washington Post)</li><li><a href="https://www.express.com/" target="_blank" rel="noreferrer noopener">express.com</a></li><li><a href="https://www.meteor.com/" target="_blank" rel="noreferrer noopener">Meteor</a>&nbsp;&amp;&nbsp;<a href="http://www.apollodata.com/" target="_blank" rel="noreferrer noopener">Apollo</a></li></ul>



<p>Those are just the ones that we know about, but I’m sure there are many others. If you’re using Apollo Server in production and your company wasn’t mentioned, let us know in the comments!</p>



<p>If you’re not using Apollo Server just yet but want to give it a try, read the next section to learn how to set it up.</p>



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



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>If you want a more in-depth introduction for how to set up a GraphQL server and connect it to SQL, Mongo or REST backends, I highly recommend doing our recently updated tutorial:&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener">How to Build a GraphQL Server</a>. It is by far the most viewed post on our blog!</p><p>A note for those who’ve used Apollo Server previously: You may notice we now import from&nbsp;<code>apollo-server-</code>&nbsp;rather than&nbsp;<code>graphql-server-</code>&nbsp;npm packages. We felt the rename better reflects that it’s part of the Apollo project and family of libraries.</p></blockquote>



<p>Here’s how easy it is to use Apollo Server once you’ve built a GraphQL schema (for example with&nbsp;<a href="https://dev-blog.apollodata.com/graphql-tools-a-simpler-way-to-create-graphql-apis-eadf018f3766" target="_blank" rel="noreferrer noopener">graphql-tools</a>).</p>



<pre class="wp-block-preformatted">import express from 'express';<br>import bodyParser from 'body-parser';<br>import {<br>  graphqlExpress,<br>  graphiqlExpress<br>} from '<strong>apollo-server-express</strong>';<br><br>const myGraphQLSchema = // ... define or import your schema here!<br>const PORT = 3000;<br><br>const app = express();<br><br>// bodyParser is needed for POST requests.<br>app.use('/graphql', bodyParser.json(), <strong>graphqlExpress</strong>({ schema: myGraphQLSchema }));// GraphiQL is reachable on http://localhost:3000/graphiql<br>app.use('/graphiql', <strong>graphiqlExpress</strong>({ endpointURL: '/graphql' }));app.listen(PORT);</pre>



<p>This example uses Express, but it’s almost the same for all other integrations. Check the&nbsp;<a href="http://dev.apollodata.com/tools/graphql-server/index.html" target="_blank" rel="noreferrer noopener">docs</a>&nbsp;or the&nbsp;<a href="https://github.com/apollographql/graphql-server" target="_blank" rel="noreferrer noopener">readme</a>&nbsp;for how to set up Apollo Server with Hapi, Koa, Lambda, Restify or Micro!</p>



<h2 class="wp-block-heading" id="38c3"><a href="#a-huge-thank-you-to-everyone-who-contributed" aria-hidden="true" class="aal_anchor" id="a-huge-thank-you-to-everyone-who-contributed"><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 huge ‘Thank You’ to everyone who contributed!</h2>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="276" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-1024x276.png" alt="" class="wp-image-1042" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-1024x276.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-300x81.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-768x207.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-1536x414.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-1200x323.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA-1980x533.png 1980w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RP0i8ZOk7Fjfq8SrSCtfnA.png 1982w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>The 1.0 release of Apollo Server would never have been possible without the hard work of all the contributors. There are two people whose contributions really stand out:&nbsp;<strong>Hagai Cohen</strong>&nbsp;and&nbsp;<strong>Nick Nance.</strong></p>



<p>Nick was there when we laid the foundation for what became Apollo Server, and he built most of the Hapi and Micro integrations. If it wasn’t for him, this project may never have gotten started. Thank you Nick!</p>



<p>Hagai came in a bit later and turned Apollo Server into what it is today. He migrated the project to Lerna, refactored large parts of the codebase and was the project’s chief maintainer for more than 6 months. Without him, Apollo Server wouldn’t be nearly as good as it is today. Thank you Hagai!</p>



<p>There were many other contributors over the course of the last year, whose big and small contributions made a difference. Thank you&nbsp;<a href="https://github.com/stubailo" target="_blank" rel="noreferrer noopener">stubailo</a>,&nbsp;<a href="https://github.com/NeoReyad" target="_blank" rel="noreferrer noopener">NeoReyad</a>,&nbsp;<a href="https://github.com/HriBB" target="_blank" rel="noreferrer noopener">HriBB</a>,&nbsp;<a href="https://github.com/nicolaslopezj" target="_blank" rel="noreferrer noopener">nicolaslopezj</a>,&nbsp;<a href="https://github.com/Urigo" target="_blank" rel="noreferrer noopener">Urigo</a>,&nbsp;<a href="https://github.com/dotansimha" target="_blank" rel="noreferrer noopener">dotansimha</a>,&nbsp;<a href="https://github.com/conrad-vanl" target="_blank" rel="noreferrer noopener">conrad-vanl</a>,&nbsp;<a href="https://github.com/spicydonuts" target="_blank" rel="noreferrer noopener">spicydonuts</a>,&nbsp;<a href="https://github.com/timneutkens" target="_blank" rel="noreferrer noopener">timneutkens</a>,&nbsp;<a href="https://github.com/creatorkuang" target="_blank" rel="noreferrer noopener">creatorkuang</a>,&nbsp;<a href="https://github.com/Tallyb" target="_blank" rel="noreferrer noopener">Tallyb</a>,&nbsp;<a href="https://github.com/kamilkisiela" target="_blank" rel="noreferrer noopener">kamilkisiela</a>,&nbsp;<a href="https://github.com/soda0289" target="_blank" rel="noreferrer noopener">soda0289</a>,&nbsp;<a href="https://github.com/kievechua" target="_blank" rel="noreferrer noopener">kievechua</a>,&nbsp;<a href="https://github.com/rdrey" target="_blank" rel="noreferrer noopener">rdrey</a>,&nbsp;<a href="https://github.com/n1mmy" target="_blank" rel="noreferrer noopener">n1mmy</a>,&nbsp;<a href="https://github.com/NeoPhi" target="_blank" rel="noreferrer noopener">NeoPhi</a>,&nbsp;<a href="https://github.com/trotzig" target="_blank" rel="noreferrer noopener">trotzig</a>,&nbsp;<a href="https://github.com/jadkap" target="_blank" rel="noreferrer noopener">jadkap</a>,&nbsp;<a href="https://github.com/RafaelCosman" target="_blank" rel="noreferrer noopener">RafaelCosman</a>,&nbsp;<a href="https://github.com/papandreou" target="_blank" rel="noreferrer noopener">papandreou</a>,&nbsp;<a href="https://github.com/ClaudiuCeia" target="_blank" rel="noreferrer noopener">ClaudiuCeia</a>,&nbsp;<a href="https://github.com/phra" target="_blank" rel="noreferrer noopener">phra</a>,&nbsp;<a href="https://github.com/nevir" target="_blank" rel="noreferrer noopener">nevir</a>,&nbsp;<a href="https://github.com/benjamn" target="_blank" rel="noreferrer noopener">benjamn</a>,&nbsp;<a href="https://github.com/pradel" target="_blank" rel="noreferrer noopener">pradel</a>,&nbsp;<a href="https://github.com/xeoneux" target="_blank" rel="noreferrer noopener">xeoneux</a>,&nbsp;<a href="https://github.com/dahjelle" target="_blank" rel="noreferrer noopener">dahjelle</a>,&nbsp;<a href="https://github.com/siegesmund" target="_blank" rel="noreferrer noopener">siegesmund</a>,&nbsp;<a href="https://github.com/sammkj" target="_blank" rel="noreferrer noopener">sammkj</a>,&nbsp;<a href="https://github.com/od1k" target="_blank" rel="noreferrer noopener">od1k</a>,&nbsp;<a href="https://github.com/pcarrier" target="_blank" rel="noreferrer noopener">pcarrier</a>,&nbsp;<a href="https://github.com/Dattaya" target="_blank" rel="noreferrer noopener">Dattaya</a>,&nbsp;<a href="https://github.com/larsw" target="_blank" rel="noreferrer noopener">larsw</a>,&nbsp;<a href="https://github.com/AlexLeung" target="_blank" rel="noreferrer noopener">AlexLeung</a>,&nbsp;<a href="https://github.com/alanchristensen" target="_blank" rel="noreferrer noopener">alanchristensen</a>,&nbsp;<a href="https://github.com/Chris-R3" target="_blank" rel="noreferrer noopener">Chris-R3</a>,&nbsp;<a href="https://github.com/ephemer" target="_blank" rel="noreferrer noopener">ephemer</a>,&nbsp;<a href="https://github.com/thebigredgeek" target="_blank" rel="noreferrer noopener">thebigredgeek</a>,&nbsp;<a href="https://github.com/comus" target="_blank" rel="noreferrer noopener">comus</a>,&nbsp;<a href="https://github.com/blakeembrey" target="_blank" rel="noreferrer noopener">blakeembrey</a>,&nbsp;<a href="https://github.com/omegablitz" target="_blank" rel="noreferrer noopener">omegablitz</a>!</p>



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



<p>Apollo Server is a community project, so if you have ideas or find a bug then don’t be shy filing issues or opening pull requests on GitHub!</p>



<p>We’re always looking for more contributors and maintainers, so if you think that could be something for you, let us know in the #contributors channel on the&nbsp;<a href="http://www.apollodata.com/#slack" target="_blank" rel="noreferrer noopener">Apollo Slack</a>&nbsp;or directly on&nbsp;<a href="https://github.com/apollographql/graphql-server" target="_blank" rel="noreferrer noopener">GitHub</a>!</p>



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



<p><em>If you liked this post and want to hear more about Apollo and GraphQL, make sure to click the “Follow” button below, and follow us on Twitter at&nbsp;</em><a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener"><em>@apollographql</em></a><em>&nbsp;and&nbsp;</em><a href="https://twitter.com/helferjs" target="_blank" rel="noreferrer noopener"><em>@helferjs</em></a><em>.</em></p>


Apollo Server 1.0 — A GraphQL server for all Node.js frameworks


<p>This is part 6 of our Full-Stack GraphQL + React Tutorial, which guides you through creating a messaging application. Each part is self-contained and focuses on a few new topics, so you can jump directly into a part that interests you or do the whole series. Here’s are the other parts of the tutorial:</p>



<ul class="wp-block-list"><li><a href="https://dev-blog.apollodata.com/full-stack-react-graphql-tutorial-582ac8d24e3b" target="_blank" rel="noreferrer noopener">Part 1: Setting up a simple client</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-part-2-server-99d0528c7928" target="_blank" rel="noreferrer noopener">Part 2: Setting up a simple server</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">Part 3: Writing mutations and keeping the client in sync</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-mutations-optimistic-ui-and-store-updates-f7b6b66bf0e2" target="_blank" rel="noreferrer noopener">Part 4: Optimistic UI and client side store updates</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5: Input Types and Custom Resolvers</a></li><li>Part 6: Server-side Subscriptions (right now)</li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-client-side-40e185e4be76" target="_blank" rel="noreferrer noopener">Part 7: GraphQL Subscriptions on the Client</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-pagination-d1c3b3ee2823" target="_blank" rel="noreferrer noopener">Part 8: Pagination</a></li></ul>



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



<p>In this tutorial, we are going to go through the process of adding GraphQL Subscriptions to our server. In Part 5, we added the concept of a message and implemented a detailed channel view in the client to display messages in each channel. But right now, messages do not sync across clients, because there’s no way for the server to notify clients that new messages have been added.</p>



<p>Just like many other applications, our messaging app needs to have real-time updates for some features, so in this tutorial we’ll build out the server-side logic to enable our client to show new messages in real time thanks to GraphQL Subscriptions. If you want to dive into the details of how subscriptions work, check out&nbsp;<a href="https://dev-blog.apollodata.com/graphql-subscriptions-in-apollo-client-9a2457f015fb" target="_blank" rel="noreferrer noopener">this blog post</a>&nbsp;introducing Apollo Client’s support for subscriptions and the&nbsp;<a href="https://github.com/facebook/graphql/blob/master/rfcs/Subscriptions.md" target="_blank" rel="noreferrer noopener">Request For C0mments</a>&nbsp;to add subscriptions to the GraphQL specification.</p>



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



<p>Let’s get started by cloning the Git repo and installing the dependencies:</p>



<pre class="wp-block-preformatted">git clone <a href="https://github.com/apollographql/graphql-tutorial.git" target="_blank" rel="noreferrer noopener">https://github.com/apollographql/graphql-tutorial.git</a><br>cd graphql-tutorial<br>git checkout t6-start<br>cd server &amp;&amp; npm install<br>cd ../client &amp;&amp; npm install</pre>



<p>First off, let’s make sure everything works by starting the server and client.</p>



<p>In one terminal session we launch the server, which will run on port 4000:</p>



<pre class="wp-block-preformatted">cd server<br>npm start</pre>



<p>And in another session we launch the client, which will run on port 3000:</p>



<pre class="wp-block-preformatted">cd client<br>npm start</pre>



<p>When you navigate your browser to&nbsp;<a href="http://localhost:3000/" target="_blank" rel="noreferrer noopener">http://localhost:3000</a>, you should enter the homepage of our messaging app, which has a list of channels that the user has created. Click on one of the channels, and you’ll be taken to the detail view that we created in the last part, where you can add new messages in the channel.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="480" height="420" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_oYyCf2u9MNCikiAvlWwmiw.gif" alt="" class="wp-image-1075"/><figcaption>What we’ve built so far</figcaption></figure>



<p>We won’t be writing any client-side code in this tutorial, but we’ll use the client UI to insert messages for testing our subscription implementation.</p>



<h2 class="wp-block-heading" id="6060"><a href="#graphql-subscriptions" aria-hidden="true" class="aal_anchor" id="graphql-subscriptions"><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>GraphQL Subscriptions</h2>



<p>To notify the client when messages are added to a channel, we’ll use GraphQL subscriptions, which allow the client to make a query and be notified of new results in the case of specific, server-side events. In our implementation of the server, we’ll use an Express server with WebSockets for pushing updates to the client.</p>



<p>In this tutorial, we’ll first add a subscription that notifies the client about new messages. Next, we’ll add a field to our GraphQL schema and implement a resolver for the subscription. Finally, we’ll use an in-memory pub-sub object that will handle passing along notifications about added messages. Together, the flow of message creations and subscription notifications will look something like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="700" height="571" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_3YNIo4y3dLFwpaYsu87qFQ.png" alt="" class="wp-image-1074" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_3YNIo4y3dLFwpaYsu87qFQ.png 700w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3YNIo4y3dLFwpaYsu87qFQ-300x245.png 300w" sizes="auto, (max-width: 700px) 100vw, 700px" /><figcaption>The data flow in an app using GraphQL subscriptions.</figcaption></figure>



<p>Let’s dive right in by adding a subscription for listening to message additions to our server-side schema! To the end of our GraphQL schema in&nbsp;<code>server/src/schema.js</code>&nbsp;we add a new root type of&nbsp;<code>Subscription</code>&nbsp;that sits on the same level as&nbsp;<code>Query</code>&nbsp;and&nbsp;<code>Mutation</code>&nbsp;. This root type contains&nbsp;<code>messageAdded(channelId: ID!)</code>, a field that represents a topic a client can listen to to be notified of messages added to a specific channel. All together, we’ve added:</p>



<pre class="wp-block-preformatted">// server/src/schema.js<br>type Subscription {<br>  messageAdded(channelId: ID!): Message<br>}</pre>



<p>Our schema now gives us a solid reference to follow as we continue to implement subscriptions.</p>



<h2 class="wp-block-heading" id="64d7"><a href="#adding-a-subscription-resolver" aria-hidden="true" class="aal_anchor" id="adding-a-subscription-resolver"><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>Adding a Subscription Resolver</h2>



<p>Now that we have a schema defining which subscriptions clients can ask for, the next step is to allow events to be sent to the subscription. To keep things simple, we’ll implement our subscription model with the in-memory&nbsp;<code>PubSub</code>&nbsp;system from the&nbsp;<code>graphql-subscriptions</code>&nbsp;package. We’ll also need to use the&nbsp;<code>withFilter</code>&nbsp;helper from the same package to split up events by which channel they are for. In&nbsp;<code>server/src/resolvers.js</code>&nbsp;we’ll start by adding the necessary import statements.</p>



<pre class="wp-block-preformatted">// server/src/resolvers.js<br>import { PubSub, withFilter } from ‘graphql-subscriptions’;</pre>



<p>Next, we’ll construct an instance of&nbsp;<code>PubSub</code>&nbsp;to handle the subscription topics for our application. We’ll add this instance right before we define&nbsp;<code>resolvers</code>, where we’ll need to use the instance to produce events when messages are created.</p>



<pre class="wp-block-preformatted"><strong>const pubsub = new PubSub();</strong>export const resolvers = {</pre>



<p>Once we have our subscription manager set up, we need to publish messages into it! With the&nbsp;<code>PubSub</code>&nbsp;class, this is as simple as calling&nbsp;<code>pubsub.publish(topic, data)</code>. For our app, we’ll publish each new message to the&nbsp;<code>messageAdded</code>&nbsp;topic along with an additional property that carries the channel ID (this will become more important later in the tutorial). One thing to note: the topic name doesn’t have to match the subscription name; we just used the same name here to keep things simple.</p>



<pre class="wp-block-preformatted">addMessage: (root, { message }) =&gt; {<br>  const channel = channels.find(channel =&gt; channel.id ===<br>message.channelId);<br>  if(!channel)<br>    throw new Error(“Channel does not exist”);  const newMessage = { id: String(nextMessageId++), text: message.text };<br>  channel.messages.push(newMessage);<strong>  pubsub.publish(‘messageAdded’, { messageAdded: newMessage, channelId: message.channelId });</strong>  return newMessage;<br>}</pre>



<p>Next, let’s use the published events to resolve subscription queries! With the&nbsp;<code>graphql-subscriptions</code>&nbsp;package, this is super easy. We set up our nested objects in&nbsp;<code>resolvers</code>&nbsp;just like we normally would, instead of returning an object at the end, we return an&nbsp;<code>AsyncIterator</code>&nbsp;that will emit the messages to send over to the client. Since the&nbsp;<code>messageAdded</code>&nbsp;topic contains events for&nbsp;<em>all</em>&nbsp;channels, we also use the&nbsp;<code>withFilter</code>&nbsp;function we imported earlier to save resources. This will filter events to select only those for the channel specified in the query. When using&nbsp;<code>withFilter</code>, the first argument is a function that returns the&nbsp;<code>AsyncIterator</code>&nbsp;we are filtering. The second argument is a condition that specifies if an event should pass through the filter given the event data and query variables.</p>



<pre class="wp-block-preformatted">Subscription: {<br>  messageAdded: {<br>    subscribe: withFilter(<br>      () =&gt; pubsub.asyncIterator(‘messageAdded’),<br>      (payload, variables) =&gt; {<br>        return payload.channelId === variables.channelId;<br>      }<br>    )<br>  }<br>}</pre>



<p>And that’s all we need for resolving a GraphQL Subscription query!</p>



<h2 class="wp-block-heading" id="56d9"><a href="#websocket-transport-for-subscriptions" aria-hidden="true" class="aal_anchor" id="websocket-transport-for-subscriptions"><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>WebSocket Transport for Subscriptions</h2>



<p>The last step in this tutorial is to add subscription support to our GraphQL server through WebSockets, since we can’t push frequent updates from the server to the client over HTTP. Thanks to&nbsp;<code>subscriptions-transport-ws</code>&nbsp;package, this is super simple! First, let’s start by adding the necessary import statements in&nbsp;<code>server/server.js</code></p>



<pre class="wp-block-preformatted">import { execute, subscribe } from ‘graphql’;<br>import { createServer } from ‘http’;<br>import { SubscriptionServer } from ‘subscriptions-transport-ws’;</pre>



<p>Next, we can open the WebSocket in our GraphQL server. We do this in two steps: first wrapping the Express server with&nbsp;<code>createServer</code>, and then using the wrapped server to set up a WebSocket to listen to GraphQL subscriptions.</p>



<pre class="wp-block-preformatted">// Wrap the Express server<br>const ws = createServer(server);ws.listen(PORT, () =&gt; {<br>  console.log(`GraphQL Server is now running on http://localhost:${PORT}`);  // Set up the WebSocket for handling GraphQL subscriptions<br>  new SubscriptionServer({<br>    execute,<br>    subscribe,<br>    schema<br>  }, {<br>    server: ws,<br>    path: '/subscriptions',<br>  });<br>});</pre>



<p>Next, we configure Graph<em>i</em>QL to use the subscriptions WebSocket we just set up.</p>



<pre class="wp-block-preformatted">server.use('/graphiql', graphiqlExpress({<br>  endpointURL: '/graphql',<br><strong>  subscriptionsEndpoint: `ws://localhost:4000/subscriptions`</strong><br>}));</pre>



<p>And with that, our server is ready for action! To try it out, we can open GraphiQL at&nbsp;<a href="http://localhost:4000/graphiql" target="_blank" rel="noreferrer noopener">http://localhost:4000/graphiql</a>&nbsp;and run the following query</p>



<pre class="wp-block-preformatted">subscription {<br>  messageAdded(channelId: 1) {<br>    id<br>    text<br>  }<br>}</pre>



<p>When you run the query, you should see a message that looks like</p>



<pre class="wp-block-preformatted">"Your subscription data will appear here after server publication!"</pre>



<p>Graph<em>i</em>QL is now listening for the creation of a new message, which we can trigger by creating a message in the client. Because we are only listening to channel 1, make sure to navigate to the first channel in the client (or directly point your browser to&nbsp;<a href="http://localhost:3000/channel/1" target="_blank" rel="noreferrer noopener">http://localhost:3000/channel/1</a>). When you create a new message, you should see it instantly show up in your Graph<em>i</em>QL window!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="530" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_O8YVfjtXV44TAYsi7hTenA.gif" alt="" class="wp-image-1073"/><figcaption>It works!</figcaption></figure>



<h2 class="wp-block-heading" id="22ae"><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>Hooray! You’ve now implemented the server-side portion of GraphQL Subscriptions by adding a subscription type to your schema and implementing a subscription transport through WebSockets! With a couple changes to our client, which will be explained in the&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-client-side-40e185e4be76" target="_blank" rel="noreferrer noopener">next tutorial</a>, our client will be able to see message additions in near real-time.</p>



<p>If you liked this tutorial and want to keep learning about Apollo and GraphQL, make sure to click the “Follow” button below, and follow us on Twitter at&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">@apollographql</a>&nbsp;and the author at&nbsp;<a href="http://twitter.com/shadajl" target="_blank" rel="noreferrer noopener">@ShadajL</a>.</p>



<p>Thanks to my mentor,&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----e51c32dc2951----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>, for his support as I wrote this post!</p>


Tutorial: GraphQL Subscriptions on the Server


<p>UI developers love GraphQL because it lets them fetch data quickly and efficiently, without having to make multiple API calls or trying to make sense of outdated documentation. With so many benefits on the client, it might seem like implementing a server to get all of these features might be very difficult. And a year and a half ago, when GraphQL had just been open sourced, it certainly looked that way! There weren’t many examples, and the syntax for defining types and fields looked pretty complicated at first glance.</p>



<p>Back in January of 2016,&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----eadf018f3766----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>&nbsp;and I were looking for ways to make working with GraphQL simpler, and there was one thing that caught our eye — the schema definition language:</p>



<pre class="wp-block-preformatted">type Person {<br>  name: String<br>  age: Int<br>  picture: Url<br>}</pre>



<p>It showed up everywhere in the&nbsp;<a href="https://facebook.github.io/graphql/#sec-Objects" target="_blank" rel="noreferrer noopener">specification</a>, but it was just used as a nice shorthand. You couldn’t actually use it to create a GraphQL server. But… what if you could? Thankfully, as we were thinking about this, GraphQL.js was quickly improving its experimental support for the schema language in the parser. There weren’t enough features yet to build a complete server with modular parts, interfaces, and more, but we were on a mission to make developing GraphQL servers as easy as possible. So, Jonas built a prototype of Apollo’s first GraphQL library,&nbsp;<a href="https://github.com/apollographql/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools</a>, which lets you create a GraphQL API using just the schema language.</p>



<h3 class="wp-block-heading" id="738f"><a href="#graphql-tools-1-0-%f0%9f%8e%89" aria-hidden="true" class="aal_anchor" id="graphql-tools-1-0-%f0%9f%8e%89"><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>graphql-tools 1.0 🎉</h3>



<p>Today, a year and a half after the project started, Jonas and I are pleased to announce the 1.0 release of&nbsp;<code>graphql-tools</code>, with special thanks to long-time contributor&nbsp;<a href="https://github.com/dxcx" target="_blank" rel="noreferrer noopener">Hagai Cohen</a>!&nbsp;<code>graphql-tools</code>&nbsp;is production-ready and has been battle-tested by dozens of companies in their production applications.</p>



<p>Here are some of the things you can do with&nbsp;<code>graphql-tools</code>:</p>



<ol class="wp-block-list"><li><a href="http://dev.apollodata.com/tools/graphql-tools/generate-schema.html" target="_blank" rel="noreferrer noopener">Create a schema</a>&nbsp;using the GraphQL Schema Definition Language, while taking advantage of&nbsp;<a href="http://dev.apollodata.com/tools/graphql-tools/resolvers.html" target="_blank" rel="noreferrer noopener">all of the features</a>&nbsp;of GraphQL.js including resolvers, interfaces, and unions</li><li>Import&nbsp;<a href="http://dev.apollodata.com/tools/graphql-tools/scalars.html" target="_blank" rel="noreferrer noopener">custom scalar types</a>&nbsp;from npm and also create your own</li><li>Completely&nbsp;<a href="http://dev.apollodata.com/tools/graphql-tools/mocking.html" target="_blank" rel="noreferrer noopener">mock your API</a>&nbsp;based on a schema definition and customize those mocks</li><li>Handle some of the&nbsp;<a href="http://dev.apollodata.com/tools/graphql-tools/errors.html" target="_blank" rel="noreferrer noopener">common errors</a>&nbsp;that come up when developing a server</li></ol>



<p>At the end, you get a regular GraphQL.js schema object, just like you would with the reference implementation directly. You can use that with your favorite GraphQL server middleware, such as&nbsp;<a href="http://dev.apollodata.com/tools/graphql-server/index.html" target="_blank" rel="noreferrer noopener">graphql-server-express</a>&nbsp;or&nbsp;<a href="https://github.com/graphql/express-graphql" target="_blank" rel="noreferrer noopener">express-graphql</a>. If there’s something you think is missing, please file an issue or submit a PR — we want to keep&nbsp;<code>graphql-tools</code>&nbsp;very lightweight and un-opinionated, but we’re always looking for potential improvements!</p>



<h2 class="wp-block-heading" id="0fc8"><a href="#building-a-simple-graphql-server" aria-hidden="true" class="aal_anchor" id="building-a-simple-graphql-server"><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>Building a simple GraphQL server</h2>



<p>If you’re new to GraphQL,&nbsp;<code>graphql-tools</code>&nbsp;is a great way to build your first server. In this post, we’ll go over some of the most basic usage, including:</p>



<ol class="wp-block-list"><li>A hello world schema (and an intro to Launchpad, a tool for learning about GraphQL servers).</li><li>A simple read-only schema with authors and posts.</li><li>The same schema with a mutation added.</li></ol>



<p>Let’s get to it, and hopefully by the end of the post you see that prototyping a simple GraphQL schema can be super easy! In future posts, we’ll cover some more advanced topics such as mocking and accessing databases and APIs.</p>



<h3 class="wp-block-heading" id="723c"><a href="#hello-world-with-graphql-tools" aria-hidden="true" class="aal_anchor" id="hello-world-with-graphql-tools"><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>Hello world with graphql-tools</h3>



<p>Here’s how you write a hello world GraphQL schema with&nbsp;<code>graphql-tools</code>:</p>



<pre class="wp-block-preformatted">import { makeExecutableSchema } from 'graphql-tools';// Construct a schema using the GraphQL schema language<br>const typeDefs = `<br>  type Query {<br>    hello: String<br>  }<br>`;// Provide resolver functions for your schema fields<br>const resolvers = {<br>  Query: {<br>    hello: (root, args, context) =&gt; {<br>      return 'Hello world!';<br>    },<br>  },<br>};// Get a GraphQL.js Schema object<br>export const schema = makeExecutableSchema({<br>  typeDefs,<br>  resolvers,<br>});</pre>



<p><a href="https://launchpad.graphql.com/new" target="_blank" rel="noreferrer noopener">Click here to see a live demo and edit the code in your browser!</a></p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>In this blog post, with every code snippet we’re going to include a link to a live example on&nbsp;<a href="https://dev-blog.apollodata.com/introducing-launchpad-the-graphql-server-demo-platform-cc4e7481fcba" target="_blank" rel="noreferrer noopener">Launchpad</a>, a new GraphQL server demo platform. Log in and click “Fork” to edit the code, or “Download” to get a Node.js app you can run locally!</p></blockquote>



<p>There are two parts that every GraphQL schema needs:</p>



<ol class="wp-block-list"><li>A schema that defines the fields and types in the API; this is kind of like the route definition in a REST API.</li><li>Resolvers, which are functions called during field execution, similar to controller methods in REST.</li></ol>



<p>Now let’s make it a bit more interesting…</p>



<h3 class="wp-block-heading" id="fea6"><a href="#nested-types-and-queries" aria-hidden="true" class="aal_anchor" id="nested-types-and-queries"><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>Nested types and queries</h3>



<p>One of the biggest benefits of a GraphQL API is that it isn’t just a flat list of endpoints — it’s actually a “graph” of types that can reference each other. Let’s create a simple API with two types that reference each other. Check out the&nbsp;<a href="https://launchpad.graphql.com/890l4w5wq" target="_blank" rel="noreferrer noopener">full example on Launchpad</a>, and we’ll highlight the important parts below:</p>



<pre class="wp-block-preformatted">type Author {<br>  id: Int!<br>  firstName: String<br>  lastName: String<br>  posts: [Post]<br>}type Post {<br>  id: Int!<br>  title: String<br>  author: Author<br>}type Query {<br>  posts: [Post]<br>  author(id: Int!): Author<br>}</pre>



<p>You can see we have both one-to-many and one-to-one relationships here: Authors have multiple posts, but each post has exactly one author.</p>



<p>The schema language is quite intuitive — the&nbsp;<code>type</code>&nbsp;keyword specifies an “object type” which can have multiple fields, and you can use&nbsp;<code>[ ]</code>&nbsp;to specify a list and&nbsp;<code>!</code>&nbsp;to specify a non-null field (all items must have an&nbsp;<code>id</code>&nbsp;in this schema). The&nbsp;<code>Query</code>&nbsp;type is special, since it defines the set of fields available at the first level of the query.</p>



<p>Let’s take a look at the resolvers here:</p>



<pre class="wp-block-preformatted">const resolvers = {<br>  Query: {<br>    posts: () =&gt; posts,<br>    author: (_, args) =&gt; find(authors, { id: args.id }),<br>  },<br>  Author: {<br>    posts: (author) =&gt; filter(posts, { authorId: author.id }),<br>  },<br>  Post: {<br>    author: (post) =&gt; find(authors, { id: post.authorId }),<br>  },<br>};</pre>



<p>These resolvers are simple functions, and in this example they read from arrays of&nbsp;<code>authors</code>&nbsp;and&nbsp;<code>posts</code>&nbsp;right in the code, since we don’t want to get into data fetching yet. Let’s take a look at that fake data:</p>



<pre class="wp-block-preformatted">const authors = [<br>  { id: 1, firstName: 'Tom', lastName: 'Coleman' },<br>  { id: 2, firstName: 'Sashko', lastName: 'Stubailo' },<br>  { id: 3, firstName: 'Mikhail', lastName: 'Novikov' },<br>];const posts = [<br>  { id: 1, authorId: 1, title: 'Introduction to GraphQL' },<br>  { id: 2, authorId: 2, title: 'GraphQL Rocks' },<br>  { id: 3, authorId: 2, title: 'Advanced GraphQL' },<br>  { id: 4, authorId: 3, title: 'Launchpad is Cool' },<br>];</pre>



<p>Note that we don’t have to specify resolvers for every field, GraphQL.js has a concept of “default resolvers”, which means it will pick up the&nbsp;<code>firstName</code>,&nbsp;<code>lastName</code>, and&nbsp;<code>title</code>&nbsp;fields on the objects for us. Let’s check out work by&nbsp;<a href="https://launchpad.graphql.com/890l4w5wq" target="_blank" rel="noreferrer noopener">running the query below</a>&nbsp;in GraphiQL on Launchpad:</p>



<pre class="wp-block-preformatted">{<br>  posts {<br>    title<br>    author {<br>      firstName<br>    }<br>  }<br>}</pre>



<p>We got some results, awesome! We can also fetch from the other perspective, starting with an author:</p>



<pre class="wp-block-preformatted">{<br>  author(id: 2) {<br>    firstName<br>    posts {<br>      title<br>    }<br>  }<br>}</pre>



<p>Great, now we’re starting to see some of the power of relationships between types in GraphQL.</p>



<h3 class="wp-block-heading" id="23d3"><a href="#adding-a-mutation" aria-hidden="true" class="aal_anchor" id="adding-a-mutation"><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>Adding a mutation</h3>



<p>For now we’ve only worked with read-only data. What if we want to update the data as well? GraphQL has a concept for this, called “mutations”. Like queries are used to fetch data, mutations are used to update something and then fetch new results.</p>



<p>First, let’s add a new type to our schema:</p>



<pre class="wp-block-preformatted">type Mutation {<br>  addPost(authorId: Int!, title: String!): Post<br>}</pre>



<p>Now, all we have to do is add a resolver for this field:</p>



<pre class="wp-block-preformatted">const resolvers = {<br>  // ... existing resolvers<br>  Mutation: {<br>    addPost: (_, args) =&gt; {<br>      const post = {<br>        id: posts.length,<br>        authorId: args.authorId,<br>        title: args.title,<br>      };      posts.push(post);<br>      <br>      return post;<br>    }<br>  }<br>};</pre>



<p>After you’re done, it should look&nbsp;<a href="https://launchpad.graphql.com/vkqrnvvp3" target="_blank" rel="noreferrer noopener">like this</a>. Now we can run the mutation in Graph<em>i</em>QL:</p>



<pre class="wp-block-preformatted">mutation AddPost {<br>  addPost(authorId: 1, title: "Added via launchpad") {<br>    id<br>    title<br>    author {<br>      firstName<br>    }<br>  }<br>}</pre>



<p>Note that in a GraphQL mutation, we can refetch as much data as we want. Then when we query all posts, we will get the new post we just added in the list! Didn’t even break a sweat, and we can already see some of the work GraphQL is doing for us with fetching related data after a mutation. To make sure you’ve followed along, check out the&nbsp;<a href="https://launchpad.graphql.com/vkqrnvvp3" target="_blank" rel="noreferrer noopener">complete example</a>.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Note: Since we’re just storing in an in-memory array, when our demo container restarts we’ll lose the data. That’s fine for a demo, but you might want to check out&nbsp;<a href="https://github.com/apollographql/awesome-launchpad/" target="_blank" rel="noreferrer noopener">one of the examples</a>&nbsp;about how to read and write to a database.</p></blockquote>



<p>Now that you have a basic setup with a few types, you can fork the project and keep working inside Launchpad, or click “Download” to edit the code locally.</p>



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



<p>If you’re as excited about advancing GraphQL technology and enabling developers as we are, join us! We’re actively hiring for&nbsp;<a href="https://www.meteor.io/jobs/#5e11e6cf-5303-4c12-a3e7-11e5f8da4be1" target="_blank" rel="noreferrer noopener">open source</a>,&nbsp;<a href="https://www.meteor.io/jobs/#b8ec842e-e79a-455e-a665-b312892d946e" target="_blank" rel="noreferrer noopener">backend</a>, and other roles to work on next-generation API technology.</p>



<figure class="wp-block-image size-large"><a href="https://www.meteor.io/team/"><img loading="lazy" decoding="async" width="800" height="533" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Fzp2zRXfoavN1e9BXudHvA.gif" alt="" class="wp-image-1097"/></a><figcaption>The Apollo and Meteor team.</figcaption></figure>



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



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="658" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_j6wIMjjl2507319QpOt4WQ-1024x658.png" alt="" class="wp-image-1098" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_j6wIMjjl2507319QpOt4WQ-1024x658.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_j6wIMjjl2507319QpOt4WQ-300x193.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_j6wIMjjl2507319QpOt4WQ-768x494.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_j6wIMjjl2507319QpOt4WQ-1200x771.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_j6wIMjjl2507319QpOt4WQ.png 1400w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A screenshot of Hello World for Medium’s preview image!</figcaption></figure>


graphql-tools: A simpler way to create GraphQL APIs

React + GraphQL Tutorial — The Server

Optimizing Your GraphQL Request Waterfalls

Full-stack React + GraphQL Tutorial


<figure class="wp-block-image"><img decoding="async" src="https://miro.medium.com/max/5092/1*OI8unw4F2B2NF37jeRaypw.png" alt=""/><figcaption>Try it today from npm!</figcaption></figure>



<p>GraphQL subscriptions are a way to add realtime data streaming to your GraphQL API. Yesterday, we wrote about an exciting new development for the community:&nbsp;<a href="https://dev-blog.apollodata.com/the-next-step-for-realtime-data-in-graphql-b564b72eb07b#.1dax8i99c" target="_blank" rel="noreferrer noopener">the new RFC to add GraphQL subscriptions to the spec</a>. Today, we’ll talk about the new versions we recently released for our GraphQL subscriptions implementation, and the work we’ve done to get to this exciting place.</p>



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



<p>On the Apollo team, we’ve been passionate about realtime data in GraphQL, and subscriptions in particular, for a long time. We&nbsp;<a href="https://dev-blog.apollodata.com/graphql-subscriptions-in-apollo-client-9a2457f015fb#.lg5kcvr7u" target="_blank" rel="noreferrer noopener">released the first version of our GraphQL subscriptions library</a>, which was the start of our exploration, almost 6 months ago in September.</p>



<p>While we initially launched this as a feature for Apollo Client, we quickly realized there was a lot of demand for this across the community, so we put together&nbsp;<a href="https://dev-blog.apollodata.com/a-proposal-for-graphql-subscriptions-1d89b1934c18" target="_blank" rel="noreferrer noopener">a proposal for a subscriptions architecture</a>&nbsp;that could work with any client or server.</p>



<p>Since then, we’ve been hard at work improving the implementation libraries, using GraphQL subscriptions internally and getting feedback from the community.</p>



<h3 class="wp-block-heading" id="9504"><a href="#the-new-releases" aria-hidden="true" class="aal_anchor" id="the-new-releases"><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 new releases</h3>



<p>In this post I want to talk about the latest releases:</p>



<ul class="wp-block-list"><li><a href="https://github.com/apollographql/graphql-subscriptions" target="_blank" rel="noreferrer noopener">graphql-subscriptions</a>&nbsp;0.3.0</li><li><a href="https://github.com/apollographql/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>&nbsp;0.5.0</li></ul>



<p>These releases included lots of merged PRs and issues fixed from community members who use GraphQL subscriptions in production. We put most of the effort into areas where we had received a lot of feedback from the community:</p>



<ul class="wp-block-list"><li>Improvements for authorization flows</li><li>More lifecycle hooks for the client, giving more control and expression with the connection</li><li>Improved websockets implementation</li><li>Integration with the MQTT protocol in addition to Redis</li></ul>



<p>The goal was to make a flexible implementation while keeping the app-specific code easier. On top of that, we wanted to create smaller and more modular package by splitting the subscriptions client and subscriptions server into separate bundles.</p>



<h2 class="wp-block-heading" id="696d"><a href="#client-and-server-lifecycle-events" aria-hidden="true" class="aal_anchor" id="client-and-server-lifecycle-events"><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>Client and server lifecycle events</h2>



<p>One of the features most requested by the community was more lifecycle events to track both the state of a subscription and the state of the connection overall. Many of the issues we closed in the last few weeks were related to this missing feature — and now it’s finally here.</p>



<p>With the new version of&nbsp;<a href="https://github.com/apollographql/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>&nbsp;you can subscribe for client lifecycle events:&nbsp;<em>connect</em>,&nbsp;<em>disconnect</em>, and&nbsp;<em>reconnect</em>.</p>



<p>This gives client developers the ability to respond to those network changes. For example, you can let the user know the app is offline, clear state after logout, disconnect the websocket, or initiate a retry after the connection has reconnected.</p>



<p>The new version also adds server lifecycle events:&nbsp;<em>connect</em>,&nbsp;<em>disconnect</em>,&nbsp;<em>subscribe</em>, and&nbsp;<em>unsubscribe</em>.</p>



<p>This gives the server developer easier control over authentication logic and the ability to clean up state on the client if the server decides to terminate the connection.</p>



<h3 class="wp-block-heading" id="bc4e"><a href="#new-init-transport-message" aria-hidden="true" class="aal_anchor" id="new-init-transport-message"><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>New INIT transport message</h3>



<p>In addition to independent life cycle events, in the new version of&nbsp;<a href="https://github.com/apollographql/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>, we added a new type of WebSocket message, called&nbsp;<code>INIT</code>&nbsp;, which gives developers the ability to pass custom arguments from the client to the server. You can think of this as a way to pass information would have been a header in HTTP.</p>



<p>Using this new type of message, you can create an authorized WebSocket by passing your authorization data in the initial request and writing code that accepts or rejects the connection before accepting subscriptions from the client using the&nbsp;<code>onConnect</code>&nbsp;callback.</p>



<p>The following example creates a GraphQL subscriptions client and server, using the new initialization feature and lifecycle events:</p>



<h3 class="wp-block-heading" id="2018"><a href="#client-js" aria-hidden="true" class="aal_anchor" id="client-js"><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>client.js</h3>



<pre class="wp-block-preformatted">import { SubscriptionClient } from ‘subscriptions-transport-ws’;const getAuthToken = () =&gt; {<br>  // Implement your logic to get the client’s auth details<br>  return ‘DUMMY_TOKEN’;<br>};const wsClient = new SubscriptionClient(`SERVER_URL_HERE`, {<br>  reconnect: true,<br>  connectionParams: {<br>    authToken: getAuthToken()<br>  }<br>});wsClient.subscribe({ query: `...` }, (errors, result) =&gt; {<br>  console.log(errors, result);<br>});// If you're using apollo, you can use `addGraphQLSubscriptions` to<br>// attach this client to your network interface</pre>



<h3 class="wp-block-heading" id="da71"><a href="#server-js" aria-hidden="true" class="aal_anchor" id="server-js"><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>server.js</h3>



<pre class="wp-block-preformatted">import { SubscriptionManager, PubSub } from ‘graphql-subscriptions’;<br>import { SubscriptionServer } from ‘subscriptions-transport-ws’;<br>import schema from ‘./schema’;const pubsub = new PubSub();<br>const subscriptionManager = new SubscriptionManager({<br>  schema,<br>  pubsub<br>});const server = createServer(); // create new connect/express serverconst subscriptionServer = new SubscriptionServer({<br>  subscriptionManager,<br>  onConnect: async ({ authToken }) =&gt; {<br>    const user = await validateUser(authToken);<br>    if (!user) {<br>      throw new Error(‘Unauthorized!’);<br>    } else { <br>      // The returned value will be part of the `context`<br>      // for the filter functions and resolvers<br>      return {<br>        user<br>      };<br>    }<br>  },<br>}, {<br>  server // or use existing server with different path<br>});</pre>



<h2 class="wp-block-heading" id="d31c"><a href="#refactor-and-dependency-improvements" aria-hidden="true" class="aal_anchor" id="refactor-and-dependency-improvements"><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>Refactor and dependency improvements</h2>



<p>We also did some code refactor and made the API more flexible. For example, you can now use a Promise for lifecycle events, setupFunctions, setting up the pub/sub engine, and more.</p>



<p>Also, there is now a&nbsp;<code>addGraphQLSubscriptions</code>&nbsp;method in the client side bundle of&nbsp;<a href="https://github.com/apollographql/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>&nbsp;so that developers using Apollo Client no longer need to write this code every time. This method allows you to extend your Apollo network interface to execute GraphQL subscriptions over the WebSocket transport, while using the regular network interface for queries and mutations.</p>



<p>We updated our implementation to use the&nbsp;<a href="https://www.npmjs.com/package/ws" target="_blank" rel="noreferrer noopener">ws</a>&nbsp;package for the server side websocket implementation. This means you can also use the client if your subscriptions client is in a server-side NodeJS environment (in browser environment, it’s better to use the native implementation of your browser).</p>



<p>The new&nbsp;<code>ws</code>&nbsp;dependency is much&nbsp;<a href="http://websockets.github.io/ws/benchmarks.html" target="_blank" rel="noreferrer noopener">faster</a>&nbsp;than our previous websocket library. It’s also smaller library and adds less overhead over the websocket standard, which means it’s easier to abstract out and change the implementation if you need to.</p>



<h2 class="wp-block-heading" id="f728"><a href="#mqtt-and-redis-support" aria-hidden="true" class="aal_anchor" id="mqtt-and-redis-support"><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>MQTT and Redis support</h2>



<p><a href="https://github.com/apollostack/graphql-subscriptions" target="_blank" rel="noreferrer noopener">graphql-subscriptions</a>&nbsp;package exports a default in-process pub/sub implementation, but for the best result in production it’s better to use an external pub/sub product, such as Redis or an MQTT service.</p>



<p>We worked with&nbsp;<a href="https://medium.com/u/c544f341ba49?source=post_page-----f11be19e6569----------------------" target="_blank" rel="noreferrer noopener">David Yahalomi</a>&nbsp;to create the&nbsp;<a href="https://github.com/davidyaha/graphql-redis-subscriptions" target="_blank" rel="noreferrer noopener">graphql-redis-subscriptions</a>&nbsp;and&nbsp;<a href="https://github.com/davidyaha/graphql-mqtt-subscriptions" target="_blank" rel="noreferrer noopener">graphql-mqtt-subscriptions</a>&nbsp;packages, which can be easily dropped in as a replacement for the default PubSub object without making any changes to the rest of your code. Using an external pub/sub system gives you more publication features — such as persistence, caching, delivery guarantees and other optimizations.</p>



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



<p>Though we’ve been working on subscriptions for a while, there’s still a lot to be done. In the near future, we’re going to be making the experience of using GraphQL subscriptions a lot better:</p>



<ul class="wp-block-list"><li><strong>GraphQL subscriptions specification.&nbsp;</strong><a href="https://medium.com/u/803918030a60?source=post_page-----f11be19e6569----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;has been&nbsp;<a href="https://dev-blog.apollodata.com/the-next-step-for-realtime-data-in-graphql-b564b72eb07b#.1dax8i99c" target="_blank" rel="noreferrer noopener">working closely</a>&nbsp;with the GraphQL team from Facebook to add subscriptions to the official spec. We’re incorporating the lessons we learned from using subscriptions in production and the feedback we hear from the community.</li><li><strong>Documentation.&nbsp;</strong>We are working on adding more documentation to our official docs site about how to add subscriptions to your app. In the meantime, the best place to read and learn about setting up GraphQL subscriptions are the&nbsp;<a href="https://github.com/apollographql/graphql-subscriptions/blob/master/README.md" target="_blank" rel="noreferrer noopener">readme</a>&nbsp;<a href="https://github.com/apollographql/subscriptions-transport-ws/blob/master/README.md" target="_blank" rel="noreferrer noopener">files</a>&nbsp;of the libraries and the&nbsp;<a href="https://github.com/apollographql/?utf8=%E2%9C%93&amp;q=githunt&amp;type=&amp;language=" target="_blank" rel="noreferrer noopener">GitHunt example</a>&nbsp;apps.&nbsp;<strong>Update</strong>: check out our new docs for&nbsp;<a href="http://dev.apollodata.com/react/subscriptions.html" target="_blank" rel="noreferrer noopener">Subscriptions with React</a>&nbsp;and&nbsp;<a href="http://dev.apollodata.com/tools/graphql-subscriptions/index.html" target="_blank" rel="noreferrer noopener">Subscriptions with GraphQL Server</a></li><li><strong>Making it easier to use subscriptions with Apollo Client.&nbsp;</strong>We&nbsp;<a href="https://github.com/apollographql/apollo-client/issues/1224" target="_blank" rel="noreferrer noopener">plan to improve</a>&nbsp;`updateQuery` and `updateQueries` and expose a simpler, yet flexible, API for updating the store when data arrives from subscriptions.</li><li><strong>Real-life case studies.&nbsp;</strong>Many of the improvements described in this post came from working on our internal apps that use these libraries, while also getting feedback from developers in the community who are using subscriptions in production. We’re going to tell that story in more detail soon.</li></ul>



<p>We’re going to write many more blog posts about those experiences and lessons we learned from using GraphQL subscriptions in production. Make sure to follow our publication so you won’t miss it!</p>



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



<p>We also want to hear more from you! Try out GraphQL subscriptions with our libraries and tell us what we should do next, and where we can best improve! And if you are&nbsp;<em>really</em>&nbsp;interested in GraphQL subscriptions and real-time features, did you know&nbsp;<a href="https://www.meteor.com/careers#open-source-engineer" target="_blank" rel="noreferrer noopener">we’re hiring</a>?</p>


New release of GraphQL Subscriptions for Javascript


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Update: There is a new version of Optics!&nbsp;<a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener"><strong>Apollo Engine</strong></a>&nbsp;has everything Optics does plus error tracking, query caching, and more. Engine is free for 1 million requests a month and it’s easy to switch from Optics to Engine using our&nbsp;<a href="https://www.apollographql.com/docs/engine/upgrade-optics.html" target="_blank" rel="noreferrer noopener"><strong>migration guide</strong></a>.</p></blockquote>



<p>Hi folks! Today, we’re going to be walking through why you should be monitoring and analyzing your GraphQL server for performance, and how Scaphold and Apollo Optics integrate to make this very easy.</p>



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



<p><em>For those that care about performance, money, UX, and scalability.</em></p>



<p>As we move into a GraphQL-first world, it’s important to be able to understand not only&nbsp;<em>what</em>&nbsp;data you’re fetching, but also&nbsp;<em>how</em>&nbsp;it’s being fetched. Many people think of this as an after-thought, hoping that simply getting as much code as possible out as fast as possible will help them win over their competition.</p>



<p>However, this approach can be costly on many levels. First, your application’s end users will notice the clunkiness of your application. In addition, on your servers, fetching data the wrong way can create inefficiencies that cost you in CPU usage, memory leaks, and slow response times (not to mention your AWS bill skyrocketing through the roof). Not the type of growth you’re looking for, probably.</p>



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



<p><em>Easily hook up Apollo Optics into your GraphQL API in a couple minutes.</em></p>



<p>Luckily, there’s a simple tool to use for GraphQL query analytics:&nbsp;<a href="http://www.apollodata.com/optics" target="_blank" rel="noreferrer noopener">Apollo Optics</a>. You can try it out for free, and it comes with a beautiful dashboard that helps you visualize your queries to gain insights on request order and response times.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="777" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_yIVQYPutR8oinOuwrtCzuQ@2x-1024x777.png" alt="" class="wp-image-515" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_yIVQYPutR8oinOuwrtCzuQ@2x-1024x777.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_yIVQYPutR8oinOuwrtCzuQ@2x-300x228.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_yIVQYPutR8oinOuwrtCzuQ@2x-768x583.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_yIVQYPutR8oinOuwrtCzuQ@2x-1200x910.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_yIVQYPutR8oinOuwrtCzuQ@2x.png 1255w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Apollo Optics: Insights and Analytics for GraphQL</figcaption></figure>



<p>GraphQL lends itself to awesome tooling like this due to its type system, where you can clearly and automatically introspect what the inputs and outputs are of a an API.</p>



<p>Here’s a step-by-step run-through of how you can create and immediately get analytics for a GraphQL app using Scaphold and Optics.</p>



<ol class="wp-block-list"><li><strong>Sign up for&nbsp;</strong><a href="https://scaphold.io/" target="_blank" rel="noreferrer noopener"><strong>Scaphold</strong></a><strong>&nbsp;and create an app.</strong></li></ol>



<p>Once you hit&nbsp;<em>Create</em>, you’ll automatically have a production-ready GraphQL server and API at your disposal.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-1024x548.png" alt="" class="wp-image-516" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-1024x548.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-300x160.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-1536x821.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-2048x1095.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-1200x642.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3dIyjaySvmPvxhehi2m_hQ-1980x1059.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>2.&nbsp;<strong>Sign up for&nbsp;</strong><a href="http://www.apollodata.com/optics" target="_blank" rel="noreferrer noopener"><strong>Apollo Optics</strong></a><strong>&nbsp;and grab your API key.</strong></p>



<p>On your Apollo Optics account, open your&nbsp;<em>app settings</em>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="549" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-1024x549.png" alt="" class="wp-image-517" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-1024x549.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-300x161.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-768x412.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-1536x823.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-2048x1098.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-1200x643.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0BvocWxcW17YGLQn4M9bsQ-1980x1062.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p><em>Copy your API key</em><strong></strong>for use in the next step.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="845" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg-1024x845.png" alt="" class="wp-image-518" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg-1024x845.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg-300x248.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg-768x634.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg-1536x1267.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg-1200x990.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_A_U2_V1LbcGv5ffTobU4xg.png 1600w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>3.&nbsp;<strong>Add Apollo Optics integration on Scaphold.</strong></p>



<p>In the Integrations Dashboard, click&nbsp;<em>Add</em>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-1024x548.png" alt="" class="wp-image-519" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-1024x548.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-300x161.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-1536x822.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-2048x1096.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-1200x642.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EfONJQjWZv2IofPqsUtdeQ-1980x1059.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p><em>Paste your API key</em>&nbsp;from earlier into the appropriate field, then hit&nbsp;<em>Create</em>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-1024x548.png" alt="" class="wp-image-520" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-1024x548.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-300x161.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-1536x822.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-2048x1097.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-1200x643.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zNs8xhzdGcWCX2zsO5Bi2A-1980x1060.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>4.&nbsp;<strong>Make a request and see it in your Optics dashboard!</strong></p>



<p>In this case, we created a couple users and queried for all of them back.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-1024x548.png" alt="" class="wp-image-521" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-1024x548.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-300x160.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-1536x821.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-2048x1095.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-1200x642.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dgKimV-SXQmu-wQMpJzr0A-1980x1059.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Our data shows up within seconds in our Apollo Optics dashboard. Hooray!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-1024x548.png" alt="" class="wp-image-522" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-1024x548.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-300x160.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-1536x821.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-2048x1095.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-1200x642.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aX9xLTSt4yvjRx7OvgseKg-1980x1059.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<h2 class="wp-block-heading" id="a8a5"><a href="#seeing-the-value" aria-hidden="true" class="aal_anchor" id="seeing-the-value"><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>Seeing the Value</h2>



<p><em>Trimming out unnecessary calls can save you time and money.</em></p>



<p>To demonstrate how much money we can save by leveraging analytics to eliminate unnecessary calls, let’s make a Stripe call to create a new customer in order to simulate Facebook’s payment flow.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation CreateStripeCustomer ($customer: CreateStripeCustomerInput!) {
  createStripeCustomer(input: $customer) {
    changedStripeCustomer {
      id
      email
      created
    }
  }
}</code></pre>



<p>Check it out in your Optics dashboard. Look at how much time that request took: 219ms.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="549" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-1024x549.png" alt="" class="wp-image-523" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-1024x549.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-300x161.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-768x412.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-1536x823.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-2048x1098.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-1200x643.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_v4v46VFz6tGL0ylPvHPihQ-1980x1062.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Looks like the bottleneck is when we’re asking for the <em>created </em>field to be returned as part of the request. We actually don’t need that value on our client, so let’s remove it.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation CreateStripeCustomer ($customer: CreateStripeCustomerInput!) {
  createStripeCustomer(input: $customer) {
    changedStripeCustomer {
      id
      email
    }
  }
}</code></pre>



<p>After running this mutation, we can see that the total request time was only 157ms.</p>



<p>Request time decreased by over 28%! 🎉</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-1024x548.png" alt="" class="wp-image-524" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-1024x548.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-300x160.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-1536x821.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-2048x1095.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-1200x642.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ctNCBGoEbHCdEh38rSWYfQ-1980x1059.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>In dollar amounts, you were able to&nbsp;<strong>save Facebook about $20 each time a new customer was created</strong>. Now, that’s pretty significant.</p>



<p>Congratulations! You’ve successfully set up powerful analytics to help you optimize your GraphQL API, and saved yourself both time and money.</p>



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



<p>Thanks for reading!</p>



<p>If you’re interested in learning more about analytics, feel free to&nbsp;<a href="http://slack.scaphold.io/" target="_blank" rel="noreferrer noopener">join our Slack channel</a>&nbsp;and ask us directly, or get started today with&nbsp;<a href="http://www.apollodata.com/optics" target="_blank" rel="noreferrer noopener">Apollo Optics</a>&nbsp;and&nbsp;<a href="https://scaphold.io/" target="_blank" rel="noreferrer noopener">Scaphold.io</a>! We’re happy to provide more information on how you can optimize your GraphQL API and more.</p>



<p><em>Originally published at&nbsp;</em><a href="https://scaphold.io/community/blog/apollo-optics-and-your-graphql-server/" target="_blank" rel="noreferrer noopener"><em>Scaphold.io</em></a><em>.</em></p>


Apollo Optics and your GraphQL Server

Navigating your transition to GraphQL


<p>We’ve been busy putting the final touches on <a rel="noreferrer noopener" href="http://www.apollodata.com/optics" target="_blank">Apollo Optics</a> for Rails. With version 0.4.2 of the agent, we’re excited to announce that Optics for Rails is ready for production workloads. Thanks to help and feedback from core members of the GraphQL and Ruby communities, including <a rel="noreferrer noopener" href="https://www.youtube.com/watch?v=Wlu_PWCjc6Y" target="_blank">Shopify</a> and <a rel="noreferrer noopener" href="https://github.com/rmosolgo/graphql-ruby" target="_blank">graphql-ruby</a> maintainer Robert Mosolgo, it came together fast!</p>



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



<p>GitHub <a rel="noreferrer noopener" href="http://githubengineering.com/the-github-graphql-api/" target="_blank">announced</a> they were moving their public API to GraphQL, and the excitement within the Rails community has been building ever since. GraphQL is a natural fit for the challenges facing Rails developers today: Front-end teams can be more productive when they no longer need to wait on back-end teams to build and maintain custom API endpoints for every feature. Communication between teams is further streamlined by GraphQL’s clean, self documenting nature. GraphQL also improves application performance and lowers infrastructure costs since clients are able to obtain all the data they need with a single request — a big win for high-traffic APIs like GitHub’s.</p>



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



<p>For all the reasons above, a growing number of prominent Rails companies have adopted GraphQL. We built Apollo Optics for Rails to help them get even more value out of GraphQL-based APIs by enabling any app built with&nbsp;<a href="https://github.com/rmosolgo/graphql-ruby" target="_blank" rel="noreferrer noopener">graphql-ruby</a>&nbsp;to understand the behavior and performance of GraphQL queries.</p>



<p>Because GraphQL clients query the exact fields they need, Optics can show you how data is used at the field level, providing insights that aren’t possible with REST APIs. For example, you can you use Optics to coordinate field deprecation, identify clients that would be affected by a schema change, validate proposed server changes against your real-world workload, identify parts of your API that are underutilized, and focus optimization efforts where they have the most impact.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="535" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-1024x535.png" alt="" class="wp-image-426" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-1024x535.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-300x157.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-768x401.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-1536x802.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-1200x626.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS-1980x1034.png 1980w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_cXbNyZ2lQ0YcjyIS.png 2000w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>See queries broken down by resolver duration</figcaption></figure>



<p>To get started using Optics with your Rails app, create an account at&nbsp;<a href="http://www.apollodata.com/optics" target="_blank" rel="noreferrer noopener">apollodata.com/optics</a>&nbsp;and follow the instructions to instrument your app. You can try Optics for free — no credit card required.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Thank you to those in the community including&nbsp;<a href="https://twitter.com/cjoudrey" target="_blank" rel="noreferrer noopener">Christian Joudrey</a>&nbsp;(Shopify),&nbsp;<a href="https://twitter.com/__xuorig__" target="_blank" rel="noreferrer noopener">Marc-Andre Giroux</a>&nbsp;(Shopify),&nbsp;<a href="https://twitter.com/chollier" target="_blank" rel="noreferrer noopener">Loic Chollier</a>&nbsp;(Quri) and&nbsp;<a href="https://twitter.com/ncavig" target="_blank" rel="noreferrer noopener">Nic Cavigliano</a>&nbsp;(Realscout) who helped build and test the Ruby agent. Special thanks to&nbsp;<a href="https://twitter.com/rmosolgo" target="_blank" rel="noreferrer noopener">Robert Mosolgo</a>&nbsp;for creating the excellent&nbsp;<a href="https://github.com/rmosolgo/graphql-ruby" target="_blank" rel="noreferrer noopener">graphql-ruby</a>&nbsp;gem and working with us to ensure that the graphql-ruby had exactly the hooks we needed to instrument queries properly and efficiently.</p></blockquote>


GraphQL analytics for your Ruby on Rails apps

How We Built GraphQL Subscriptions with Apollo


<p>One of the great things about GraphQL is that as a specification, not an implementation, it has been adopted in a wide variety of backend environments. All developers can benefit from GraphQL while continuing to enjoy the unique things about their platform of choice.</p>



<p>Last week at&nbsp;<a href="http://graphqlsummit.com/" target="_blank" rel="noreferrer noopener">GraphQL Summit</a>&nbsp;we launched&nbsp;<a href="http://www.apollodata.com/optics" target="_blank" rel="noreferrer noopener">Apollo Optics</a>, a GraphQL performance and usage monitoring software product. We think Optics will be an integral tool to running GraphQL servers on all platforms; and as we’ve begun building out our support for those platforms, we’ve discovered differences in the execution models of GraphQL servers that are quite interesting — and with Ruby in particular.</p>



<h2 class="wp-block-heading" id="eb1b"><a href="#building-agents-for-js-and-ruby-servers" aria-hidden="true" class="aal_anchor" id="building-agents-for-js-and-ruby-servers"><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>Building agents for JS and Ruby servers</h2>



<p>Today we’ve built a production-ready agent (the tool that collects the statistics about the queries that are running against your servers) for the reference JavaScript GraphQL servers, and our early access customers, including our own Galaxy PaaS, have used it to optimize their query execution.</p>



<p>Also, I’ve been involved in building an agent for Ruby-based servers that use the&nbsp;<a href="https://github.com/rmosolgo/graphql-ruby" target="_blank" rel="noreferrer noopener">graphql-ruby</a>&nbsp;gem. With graphql-ruby’s author Robert Mosolgo, and Shopify, who’ve created the popular&nbsp;<a href="https://github.com/Shopify/graphql-batch" target="_blank" rel="noreferrer noopener">graphql-batch</a>&nbsp;gem used to group together database access, I’ve put an initial beta version together for users to try out.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><em>We’ve also heard from many users who are keen to use Optics in other environments, and we’re working hard on enabling those agents. If you’d like to help build an agent for your platform of choice, get in touch with us via the #optics-agent-dev channel in our&nbsp;</em><a href="http://www.apollodata.com/#slack" target="_blank" rel="noreferrer noopener"><em>Apollo Slack</em></a><em>.</em></p></blockquote>



<p>Along the way, I’ve discovered some interesting things about the execution model of GraphQL in Ruby, which comes as a bit of a surprise as someone who has only written his GraphQL servers in NodeJS so far. I think it makes for an interesting journey!</p>



<h2 class="wp-block-heading" id="7e28"><a href="#experimenting-with-githunt" aria-hidden="true" class="aal_anchor" id="experimenting-with-githunt"><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>Experimenting with GitHunt</h2>



<p>The principal app I’ve been testing our agent against is&nbsp;<a href="https://github.com/apollostack/githunt-api-rails" target="_blank" rel="noreferrer noopener">a version</a>&nbsp;of the&nbsp;<a href="https://github.com/apollostack/githunt-api" target="_blank" rel="noreferrer noopener">GitHunt API server</a>&nbsp;written in Ruby on Rails.&nbsp;<a href="https://github.com/apollostack/githunt-react" target="_blank" rel="noreferrer noopener">GitHunt</a>&nbsp;is a simple “Hacker News” of GitHub repositories, and stores some data in a local SQLite database, as well as querying GitHub’s REST API for repository and user data. The GraphQL server combines these sources behind a single&nbsp;<a href="http://dev.apollodata.com/react/example-schema.html" target="_blank" rel="noreferrer noopener">schema</a>.</p>



<p>My reference implementation is the NodeJS version of the server. When you run a query such as:</p>



<pre class="wp-block-preformatted">query Feed {<br>  feed (type: NEW, limit: 3) {<br>    repository {<br>      owner { login }<br>      name<br>    }    postedBy { login }<br>    <br>    vote {<br>      vote_value<br>    }<br>  }<br>}</pre>



<p>Execution happens in around 800ms, and the trace in Optics looks like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="912" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-1024x912.png" alt="" class="wp-image-404" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-1024x912.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-300x267.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-768x684.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-1536x1367.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-2048x1823.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-1200x1068.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-gMCYbD6JhavxkAM0Gkbqg-1980x1763.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>The three entries get grabbed first (via a SQL query); then in parallel, we get :</p>



<ul class="wp-block-list"><li>the user posting (over REST from GitHub),</li><li>the repository info (also over REST from GH)</li><li>some vote information (from SQL)</li></ul>



<h2 class="wp-block-heading" id="b126"><a href="#rubys-execution" aria-hidden="true" class="aal_anchor" id="rubys-execution"><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>Ruby’s execution</h2>



<p>In Ruby the behavior is quite different. Using the default execution strategy I quickly noticed that (unsurprisingly) execution happened in serial, leading to extremely long total query times and traces like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="912" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-1024x912.png" alt="" class="wp-image-403" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-1024x912.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-300x267.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-768x684.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-1536x1367.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-2048x1823.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-1200x1068.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MIsDURxIpRzxmAZ7l42N_A-1980x1763.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>To try and improve performance, and to more closely mirror what users have told us they’re using in real production environments, I tried the&nbsp;<a href="https://github.com/Shopify/graphql-batch" target="_blank" rel="noreferrer noopener">graphql-batch</a>&nbsp;gem, which allow you to resolve a set of fields together via a “loader” mechanism.</p>



<p>This is especially useful for loading many of the same type of object (the Entry.posted field, for example,which is loaded from three entries) if fetching multiple objects at once is faster than fetching each one individually.</p>



<p>For a database query like fetching the user’s vote for an entry, this is certainly the case as we can use a SELECT .. FROM (X, Y, Z) .</p>



<p>For a third-party API request like Entry.postedBy and Entry.repository (which fetch data from GitHub), the loader mechanism allowed me to easily use the parallel gem to perform the HTTP requests in separate threads).</p>



<p>When running with these loaders, I saw a trace like:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="912" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-1024x912.png" alt="" class="wp-image-402" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-1024x912.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-300x267.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-768x684.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-1536x1367.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-2048x1823.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-1200x1068.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_utEyrfZ2Cm9tabWQ2WldQg-1980x1763.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>You can see in the trace that each&nbsp;<em>type</em>&nbsp;of field resolves together (within the loader responsible for that field type), but the three different resolvers still execute serially. This was surprising to me. I expected the loaders, which use a promise-based asynchronous execution mechanism, to resolve simultaneously, which is how things work in the NodeJS case above.</p>



<p>One of the benefits of GraphQL is the execution model allows us to parallelize many field accesses, so it seems fruitful to try and get those loaders to execute in parallel.</p>



<h2 class="wp-block-heading" id="99cb"><a href="#threading-loaders" aria-hidden="true" class="aal_anchor" id="threading-loaders"><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>Threading loaders</h2>



<p>As a proof of concept, I again used the parallel gem to run loaders over multiple threads.&nbsp;<a href="https://github.com/tmeasday/graphql-batch/commit/2a07a70ec1fd93286117e67c0ca8dc528c2187c2" target="_blank" rel="noreferrer noopener">The code</a>&nbsp;is quite simple:</p>



<pre class="wp-block-preformatted">Parallel.each(loaders.values, in_threads: 4) do |loader|<br>  loader.resolve<br>end</pre>



<p>Using that, I get the trace below, which is now in line with the JS version:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="912" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-1024x912.png" alt="" class="wp-image-401" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-1024x912.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-300x267.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-768x684.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-1536x1367.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-2048x1823.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-1200x1068.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JX3Mk84eLWLxY1z4aPM0Qg-1980x1763.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>It’s perhaps not surprising that the default Ruby GraphQL execution models are serial, given Ruby (and Rails in particular) come with a set of assumptions about a single request’s code being single threaded. These include Rails’ historical lack of thread safety, and assumptions about db connection pools sizes on the server.</p>



<p>Also, as we saw, it’s certainly possible to use a single loader to thread certain kinds of concurrent accesses in a straightforward way.</p>



<p>However, I think there is a case for a true “parallel async” execution model in graphql-ruby, which if used carefully could drastically improve request latencies in queries that are similar to this GitHunt example. There’s currently an&nbsp;<a href="https://github.com/rmosolgo/graphql-ruby/issues/274" target="_blank" rel="noreferrer noopener">active thread</a>&nbsp;on the graphql-ruby repo discussing exactly this, and we can hope to see a true parallel execution model soon.</p>



<p>I’m excited to see how this area moves forward, and how the different execution strategies in the various runtime environments inform each other. We think Optics is a great way to visualize this data and should help driving things forward!</p>


Tracing Ruby’s GraphQL execution


<figure class="wp-block-image"><img decoding="async" src="https://miro.medium.com/max/3038/1*h1RDyEx7ccDzrxK86tgjfg.png" alt=""/><figcaption>This is a specific collection of packages we put together for a Node.js server and a JavaScript client, but an equivalent set of packages can and should exist for every server and client platform.</figcaption></figure>



<p>Real-time subscriptions have been an exciting topic in the GraphQL community almost from the start.&nbsp;<a href="https://medium.com/u/8d9de11eda52?source=post_page-----1d89b1934c18----------------------" target="_blank" rel="noreferrer noopener">Laney Kuenzel</a>&nbsp;has given several talks about&nbsp;<a href="https://medium.com/apollo-stack/new-features-in-graphql-batch-defer-stream-live-and-subscribe-7585d0c28b07#.n5am6tg1c" target="_blank" rel="noreferrer noopener">Facebook’s internal implementation of subscriptions</a>, and there have been a few community implementations. Unfortunately, a lot of these have been coupled to specific frameworks or application architectures, so it’s been hard for GraphQL subscriptions to take off as a standard.</p>



<p>We wanted to build something anyone can integrate into their servers and clients, without reinventing the common features any implementation would need. That way, as a community we can start building and sharing integrations for different backends, such as Redis, PostgreSQL triggers, Kafka, and more.</p>



<p>That’s why we are shipping an open-source GraphQL subscriptions implementation designed to be as general as possible.</p>



<h2 class="wp-block-heading" id="992c"><a href="#the-core-packages" aria-hidden="true" class="aal_anchor" id="the-core-packages"><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 core packages</h2>



<p>Today, I’d like to introduce you to two packages in particular:</p>



<ol class="wp-block-list"><li><a href="https://github.com/apollostack/graphql-subscriptions" target="_blank" rel="noreferrer noopener"><strong>graphql-subscriptions</strong></a>, a package you can use to manage parsing, pub/sub handling, and execution for GraphQL subscriptions with GraphQL.js, Facebook’s reference JavaScript implementation. This is completely transport and backend independent, and only implements the kinds of things we think could be part of the spec for GraphQL subscriptions some day.</li><li><a href="https://github.com/apollostack/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener"><strong>subscriptions-transport-ws</strong></a>, a server and client implementation of a simple Websocket protocol for GraphQL subscriptions. This is not coupled to any specific GraphQL clients, and can be used from Apollo, Relay, or just plain JavaScript. It implements subscribing, unsubscribing, and receiving new results or errors for subscriptions. You can easily run it alongside your HTTP server, and plug it into your schema via the graphql-subscriptions package above.</li></ol>



<p>We’re getting started on integrating GraphQL subscriptions into our production apps, but we wanted to open source the tools above up front, so that we can all work together on them as a community. If this sounds interesting, try them out, and open an issue or maybe file a PR with an improvement.</p>



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



<p><a href="https://github.com/apollostack/graphql-subscriptions" target="_blank" rel="noreferrer noopener">GitHub</a>,&nbsp;<a href="https://www.npmjs.com/package/graphql-subscriptions" target="_blank" rel="noreferrer noopener">npm</a></p>



<p>When you build an HTTP-based GraphQL server in JavaScript, you usually use Facebook’s reference GraphQL.js execution engine, which accepts a query string and a schema and returns a result. The&nbsp;<em>graphql-subscriptions</em>&nbsp;package is a small wrapper around GraphQL.js that can execute subscriptions as well.</p>



<p>The main component of&nbsp;<em>graphql-subscriptions</em>&nbsp;is the&nbsp;<strong>SubscriptionManager</strong>, which takes a schema, a pub-sub handler, and some optional configuration in the form of&nbsp;<em>setup functions</em>, and creates an object which can execute subscriptions in response to pub-sub events.</p>



<p>What is a&nbsp;<em>setup function</em>? Well, it’s simple. While queries and mutations execute in one step, GraphQL subscriptions run in two steps:</p>



<ol class="wp-block-list"><li>Receive the subscription string, validate it, store it, and set up any state necessary on the server to subscribe to the right channels.</li><li>Receive a pub-sub message on some channel, execute the subscription, and send the result to the client.</li></ol>



<p>The second step is handled by your GraphQL resolvers, as usual. But the first is a new thing, and that’s what the setup functions in the GraphQL subscriptions package do. By default, they just use the subscription field as the channel name, which makes it easy to write simple demos.</p>



<p>The best part about <em>graphql-subscriptions</em> is that it’s totally decoupled from the pub-sub system and transport you are using. For example, you can plug it into a <a rel="noreferrer noopener" href="https://medium.com/apollo-stack/graphql-subscriptions-with-redis-pub-sub-f636fc84a0c4#.i7bxnctwy" target="_blank">Redis implementation</a> we recently blogged about. What about the transport? Well, before we move on to the transport, let’s run some very simple GraphQL subscriptions using just GraphQL.js and the <em>graphql-subscriptions</em> package:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// npm install graphql graphql-tools graphql-subscriptions
const { PubSub, SubscriptionManager } = require(&#039;graphql-subscriptions&#039;);
const { makeExecutableSchema } = require(&#039;graphql-tools&#039;);

// Our &quot;database&quot;
const messages = [];

// Minimal schema
const typeDefs = `
type Query {
  messages: [String!]!
}
type Subscription {
  newMessage: String!
}
`;

// Minimal resolvers
const resolvers = {
  Query: { messages: () =&gt; messages },
  // This just passes through the pubsub message contents
  Subscription: { newMessage: (rootValue) =&gt; rootValue },
};

// Use graphql-tools to make a GraphQL.js schema
const schema = makeExecutableSchema({ typeDefs, resolvers });

// Initialize GraphQL subscriptions
const pubsub = new PubSub();
const subscriptionManager = new SubscriptionManager({ schema, pubsub });

// Run a subscription
subscriptionManager.subscribe({
  query: `
    subscription NewMessageSubscription {
      newMessage
    }
  `,
  callback: (err, result) =&gt;
    console.log(`New message: ${result.data.newMessage}`),
});

// Create a message
const helloWorldMessage = &#039;Hello, world!&#039;;

// Add it to &quot;database&quot;
messages.push(helloWorldMessage);

// Push it over pubsub, this could be replaced with Redis easily
pubsub.publish(&#039;newMessage&#039;, helloWorldMessage);

// Prints &quot;New message: Hello, world!&quot; in the console via the subscription!</code></pre>



<p>As you can see, the&nbsp;<em>graphql-subscriptions</em>&nbsp;package is the only thing you need to start running subscriptions against your schema and getting updates. Just like there is often one popular GraphQL execution engine for each server-side language, we think there should be one core subscription implementation, so that people can target it when writing tools and backend integrations. See how this is possible by&nbsp;<a href="https://medium.com/apollo-stack/graphql-subscriptions-with-redis-pub-sub-f636fc84a0c4#.wejfu4x6i" target="_blank" rel="noreferrer noopener">reading about the Redis integration</a>.</p>



<p>But it’s not quite enough to go off and write a real app; you also need some way to get those results from a client. That’s where the transport comes in.</p>



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



<p><a href="https://github.com/apollostack/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">GitHub</a>,&nbsp;<a href="https://www.npmjs.com/package/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">npm</a></p>



<p>This package includes a client and server that works with&nbsp;<em>graphql-subscriptions</em>&nbsp;from above. It defines a minimal websocket protocol that only includes support for starting and stopping subscriptions, and receiving data. It doesn’t even support queries and mutations, since we think it’s currently best to do those over the more standard HTTP transport. Here’s a summary of the messages used by the transport at the time of writing:</p>



<ul class="wp-block-list"><li>Client to server: SUBSCRIPTION_START, SUBSCRIPTION_END</li><li>Server to client: SUBSCRIPTION_SUCCESS, SUBSCRIPTION_FAIL, SUBSCRIPTION_DATA</li></ul>



<p>As you can see, there is nothing extra in there — just the minimal set of operations needed to run subscriptions. It’s designed to run alongside your existing GraphQL setup.</p>



<p>Here’s how easy it is to add GraphQL subscriptions to a basic Node server using this package:</p>



<pre class="wp-block-preformatted">import { createServer } from 'http';<br>import { SubscriptionServer } from 'subscriptions-transport-ws';const websocketServer = createServer((request, response) =&gt; {<br>  response.writeHead(404);<br>  response.end();<br>});<br><br>websocketServer.listen(WS_PORT, () =&gt; console.log(<br>  `Websocket Server is now running on http://localhost:${WS_PORT}`<br>));<br><br>new SubscriptionServer(<br>  { subscriptionManager },<br>  websocketServer<br>);</pre>



<p>As you can see we just pass the&nbsp;<em>subscriptionManager</em>&nbsp;we created above into a new&nbsp;<strong>SubscriptionServer</strong>&nbsp;instance, which attaches itself to a regular Node web server. You can also pass any options you need, such as a per-subscription&nbsp;<em>context</em>.</p>



<p>Now let’s try calling this subscription over the network, instead of before when we had it in-process!</p>



<h2 class="wp-block-heading" id="3920"><a href="#running-a-simple-subscription-in-js" aria-hidden="true" class="aal_anchor" id="running-a-simple-subscription-in-js"><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>Running a simple subscription in JS</h2>



<p>Luckily, the <em>subscriptions-transport-ws</em> package also includes a handy client implementation, which we can use to connect to our server and run some subscriptions:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// To run this code yourself:
// 1. Download and run the demo server: https://github.com/apollostack/frontpage-server
// 2. Use create-react-app to create a build system
// 3. npm install subscriptions-transport-ws
// 4. Replace all of the code in src/ with just this file

import { Client } from &#039;subscriptions-transport-ws&#039;;

const client = new Client(&#039;ws://localhost:8090&#039;);

client.subscribe({
  query: `
    subscription UpvotedPostSubscription {
      postUpvoted {
        title
        votes
      }
    }
  `
}, (err, res) =&gt; {
  if (err) {
    console.error(err);
    return;
  }

  console.log(`&quot;${res.postUpvoted.title}&quot; has ${res.postUpvoted.votes} votes now.`);
})</code></pre>



<p>As you can see, this package is very tiny. It only implements the transport, and doesn’t integrate with any fancy libraries, providing only a basic callback-style interface. Together, we can easily set this up to work with observables, Redux, Apollo, Relay, and any other client-side technology we like to use in our apps.</p>



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



<p>We hope that by the end of the year GraphQL subscriptions are going to be one of the three main operations people expect from their server:&nbsp;<em>query, mutation, and subscription</em>.</p>



<p>To make this happen, there is still some work to do:</p>



<ol class="wp-block-list"><li><strong>Servers:</strong>&nbsp;We’re excited to work with GraphQL server authors to implement support for a&nbsp;<a href="https://github.com/apollostack/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">common transport</a>, and work on other pub-sub plugins for Kafka, Postgres triggers, and more. Let us know if you’re interested!</li><li><strong>Clients:</strong>&nbsp;Apollo has support for subscriptions built in, and we should add integration with other frontend libraries and tools such as Relay and GraphiQL.</li><li><strong>Spec:</strong>&nbsp;We’re working hard to figure out what parts of GraphQL subscriptions are common to all implementations, and should be core to the GraphQL specification. Look out for a post about this soon!</li></ol>



<p>The coolest thing about GraphQL is that it’s an open spec and community, not just one implementation. So let’s work together to move it into the future!</p>


A proposal for GraphQL subscriptions

GraphQL subscriptions with Redis Pub Sub


<p>In September of 2016 GitHub casually dropped some big news when they&nbsp;<a href="http://githubengineering.com/the-github-graphql-api/" target="_blank" rel="noreferrer noopener">officially announced</a>&nbsp;their new GraphQL API and made it available to everyone in&nbsp;<a href="https://developer.github.com/early-access/" target="_blank" rel="noreferrer noopener">early access</a>.</p>



<p>In this post I’ll explain the most important things you need to know about GitHub’s GraphQL API:</p>



<ol class="wp-block-list"><li><strong>Why it matters</strong></li><li><strong>What it looks like&nbsp;</strong>(also check out the&nbsp;<a href="https://youtu.be/6xO87LlijoQ" target="_blank" rel="noreferrer noopener">video tour</a>!)</li><li><strong>How you can use it</strong></li><li><strong>What’s coming next</strong></li></ol>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>If you don’t yet know what GraphQL is, go check out the excellent introduction on&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">graphql.org</a>&nbsp;before reading the rest of this post. You’ll get more out of it.</p></blockquote>



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



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



<p>For years, GitHub’s REST API has been used by others as a great example of a well-designed REST API, and many companies modeled their REST API after GitHub’s.</p>



<p>If GitHub’s REST API was so good, why are they moving to GraphQL? For the same reasons that many other companies have started adopting GraphQL. You can read the details in their&nbsp;<a href="http://githubengineering.com/the-github-graphql-api/" target="_blank" rel="noreferrer noopener">announcement post</a>, but the gist of it is this:</p>



<ul class="wp-block-list"><li>Where REST requires many requests, GraphQL takes just one</li><li>With REST, you request too much or too little data; with GraphQL you request exactly what you need</li><li>REST often turns into a maze of poorly-documented endpoints; GraphQL is strongly-typed and self-documenting</li></ul>



<p>In the words of the GitHub platform team:</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>GraphQL represents a&nbsp;<strong>massive leap forward for API development</strong>. Type safety, introspection, generated documentation, and predictable responses benefit both the maintainers and consumers of our platform. We’re looking forward to our new era of a GraphQL-backed platform, and we hope that you do, too!</p></blockquote>



<p>Thanks to GraphQL, GitHub no longer needs to separately maintain a public and a private API. Instead there will be just one API, used for both.</p>



<p>GitHub’s announcement is so significant because their new API is the first large-scale, public GraphQL API, and&nbsp;<strong>where GitHub goes many others will follow.&nbsp;</strong>On top of that, other notable companies are&nbsp;<em>already</em>&nbsp;using GraphQL, including Facebook, Twitter, Intuit, Shopify, and many more. There’s so much interest that the&nbsp;<a href="http://graphqlsummit.com/" target="_blank" rel="noreferrer noopener">first GraphQL conference</a>&nbsp;ever is coming to San Francisco this October.</p>



<p>But enough about why this is so exciting, let’s take a look at their actual API.</p>



<h2 class="wp-block-heading" id="c5d7"><a href="#what-it-looks-like" aria-hidden="true" class="aal_anchor" id="what-it-looks-like"><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 it looks like</h2>



<p>If you sign their prerelease agreement, you get early access to the GitHub GraphQL API. I did just that, and then headed straight to the API Explorer. Those familiar with GraphQL will recognize it as&nbsp;<a href="https://medium.com/the-graphqlhub/graphiql-graphql-s-killer-app-9896242b2125#.vcy9lc4ph" target="_blank" rel="noreferrer noopener">Graph<em>i</em>QL</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="539" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA-1024x539.png" alt="" class="wp-image-336" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA-1024x539.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA-300x158.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA-768x404.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA-1536x809.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA-1200x632.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_51SBnuBFxAGu9Vpw8V8KNA.png 1592w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Exploring GitHub’s GraphQL API with GraphiQL</figcaption></figure>



<p>After a couple seconds of typing, I sent my first query and got back a response — it worked! I could have used GraphiQL to explore the schema, but it’s not the easiest way to get a quick overview, so I turned to the&nbsp;<a href="https://developer.github.com/early-access/graphql/" target="_blank" rel="noreferrer noopener">API documentation</a>&nbsp;to find out what queries or mutations I could make. The starting points for queries were pretty much as expected: you can search for things, look up users and organizations, and get info about yourself using the&nbsp;<em>viewer</em>&nbsp;query. From there you can drill deeper and get lists of repositories, which in turn let you get PRs, issues, comments, reactions (the emojis), forks, branches, commits and even the Git trees of individual commits. And that’s really only the tip of the iceberg. Pretty cool, right?</p>



<p>Next up, I took a look at the mutations — GraphQL’s way of modifying data. The selection there is a lot more limited. Right now, the only things you can do are comment on issues, add reactions to comments, subscribe/unsubscribe from issues, and manage projects — a new feature GitHub introduced yesterday, and which is powered by GraphQL.</p>



<p>Of course, I had to try posting a comment via the new GraphQL API:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="153" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA-1024x153.png" alt="" class="wp-image-335" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA-1024x153.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA-300x45.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA-768x115.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA-1536x230.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA-1200x180.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_7_UGSQL9sRDocXq8CgMKtA.png 1564w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>My first comment made via GitHub’s GraphQL API</figcaption></figure>



<p>Here’s a&nbsp;<a href="https://github.com/apollostack/apollo/issues/66" target="_blank" rel="noreferrer noopener">link to the issue</a>. Go give it a try, and see if you can post to it via GitHub’s GraphQL API!</p>



<p>Overall, I think the existing parts of the API are already in excellent shape, and there were just a few rough edges:</p>



<ul class="wp-block-list"><li>The API documentation was slightly outdated and incomplete in places. I worked around it by using the introspection query to print myself a neat little schema in GraphQL schema language (<a href="https://gist.github.com/helfer/16ae2323ff3c23cedc69471a973a4f0f" target="_blank" rel="noreferrer noopener">see the schema</a>).</li><li>Connections (<a href="https://medium.com/apollo-stack/understanding-pagination-rest-graphql-and-relay-b10f835549e7" target="_blank" rel="noreferrer noopener">a type of pagination</a>) are used extensively, which can make initial interaction with the API quite confusing for people who are not familiar with connections.</li><li>All mutations take only one input argument, which makes them harder to write and read. This was done because of a&nbsp;<a href="https://github.com/facebook/relay/issues/112" target="_blank" rel="noreferrer noopener">limitation in Relay</a>, but Relay 2 is going to remove that limitation, and&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;already supports multiple arguments today.</li></ul>



<p><strong><em>Edit (9/16)</em></strong><em>: I felt like this post didn’t adequately cover how powerful the GraphQL API is, so I made a quick video tour for anyone who wants to see more:</em></p>



<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube wp-embed-aspect-4-3 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="A quick tour of GitHub&#039;s GraphQL API" width="580" height="435" src="https://www.youtube.com/embed/6xO87LlijoQ?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



<h2 class="wp-block-heading" id="10df"><a href="#how-you-can-use-it" aria-hidden="true" class="aal_anchor" id="how-you-can-use-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>How you can use it</h2>



<p>Once you’ve signed the prerelease agreement, you can start building your own apps against GitHub’s GraphQL API. Technically you can send your GraphQL queries as simple strings in a POST request, but your life is going to be a lot easier if you use a GraphQL client like&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;or&nbsp;<a href="https://github.com/facebook/relay" target="_blank" rel="noreferrer noopener">Relay</a>.</p>



<p>To make your life even easier, we’ve built an&nbsp;<a href="https://github.com/apollostack/GitHub-GraphQL-API-Example" target="_blank" rel="noreferrer noopener">example mobile app</a>&nbsp;with React Native. It’s a small GitHub issue reader that demonstrates how you can use the GraphQL API. You’re more than welcome to contribute to it by adding features or fixing bugs!</p>



<figure class="wp-block-image size-large"><a href="https://www.dropbox.com/s/dcmh6u0hau54609/Screenshot%202016-09-15%2010.08.35.png?dl=0"><img loading="lazy" decoding="async" width="1024" height="691" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_rkk8F2td5pKnijw5RXnGRg-1024x691.png" alt="" class="wp-image-334" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_rkk8F2td5pKnijw5RXnGRg-1024x691.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rkk8F2td5pKnijw5RXnGRg-300x202.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rkk8F2td5pKnijw5RXnGRg-768x518.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rkk8F2td5pKnijw5RXnGRg-1200x810.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rkk8F2td5pKnijw5RXnGRg.png 1366w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></a><figcaption>IssueReader: an example app for GitHub’s new GraphQL API</figcaption></figure>



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



<p>This is just the start of GitHub’s GraphQL API, and there’s a lot more to come. The API will be refined during early access, and the GitHub team hopes to add support for features like batching, subscriptions and deferring to their server (Apollo Client already supports&nbsp;<a href="https://medium.com/apollo-stack/query-batching-in-apollo-63acfd859862" target="_blank" rel="noreferrer noopener">batching</a>&nbsp;and&nbsp;<a href="https://medium.com/apollo-stack/graphql-subscriptions-in-apollo-client-9a2457f015fb" target="_blank" rel="noreferrer noopener">subscriptions</a>!)</p>



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



<p>If all that talk about GraphQL got you curious, you’ll definitely want to look at the following posts and resources to learn more about it.</p>



<p><strong>Blog posts + tutorials:</strong></p>



<ul class="wp-block-list"><li><a href="https://medium.com/apollo-stack/why-graphql-is-the-future-3bec28193807" target="_blank" rel="noreferrer noopener">Why GraphQL is the future</a></li><li><a href="https://medium.com/apollo-stack/the-concepts-of-graphql-bc68bd819be3" target="_blank" rel="noreferrer noopener">GraphQL concepts visualized</a></li><li><a href="https://medium.com/apollo-stack/graphql-the-next-generation-of-api-design-f24b1689756a" target="_blank" rel="noreferrer noopener">GraphQL: the next generation of API design</a></li><li><a href="https://medium.com/apollo-stack/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener">Tutorial: how to build your own GraphQL server</a></li><li>… and more&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">on our blog</a></li></ul>



<p><strong>Resources:</strong></p>



<ul class="wp-block-list"><li><a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL.org</a></li><li><a href="http://www.apollostack.com/" target="_blank" rel="noreferrer noopener">Apollo</a></li><li><a href="https://learngraphql.com/" target="_blank" rel="noreferrer noopener">learngraphql.com</a></li></ul>



<p>Last but not least: As we mentioned before, the&nbsp;<a href="http://graphqlsummit.com/" target="_blank" rel="noreferrer noopener">first-ever GraphQL conference</a>&nbsp;is happening in SF on October 26th! GitHub’s Brandon Black will talk more about how his team built the new GraphQL API, along with speakers from Facebook Open Source, Angular, Apollo, and more.</p>



<figure class="wp-block-image size-large"><a href="http://graphqlsummit.com/"><img loading="lazy" decoding="async" width="1024" height="512" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_TAk4fIBMvN8tEOdhBSusCQ-1024x512.png" alt="" class="wp-image-333" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_TAk4fIBMvN8tEOdhBSusCQ-1024x512.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TAk4fIBMvN8tEOdhBSusCQ-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TAk4fIBMvN8tEOdhBSusCQ-768x384.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TAk4fIBMvN8tEOdhBSusCQ.png 1200w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></a></figure>


The GitHub GraphQL API


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This post was written as a response to Kin Lane’s post,&nbsp;<a href="http://apievangelist.com/2016/08/30/graphql-seems-like-we-do-not-want-to-do-the-hard-work-of-api-design/" target="_blank" rel="noreferrer noopener">“GraphQL Seems Like We Do Not Want To Do The Hard Work Of API Design.”</a>&nbsp;Since then, Kin has published a follow-up,&nbsp;<a href="https://apievangelist.com/2016/09/02/i-am-keeping-my-mind-open-and-looking-forward-to-learning-more-about-graphql/" target="_blank" rel="noreferrer noopener">“I Am Keeping My Mind Open And Looking Forward To Learning More About GraphQL”</a></p></blockquote>



<p>I sometimes hear people talk about how GraphQL is too complicated to be a good replacement for REST. I strongly disagree, and felt it would be useful to present an alternative point of view on the topic.</p>



<p>APIs are a core building block of the Internet as we know it, and the methods by which different services interact enable a lot of the information sharing and gathering we have come to take for granted. It’s important that the technologies with which we build and use APIs are as helpful and simple as possible.</p>



<p>A little background: I have always identified as a frontend developer — a person primarily interested in delivering great products to people and sweating the details of user experience, interactions, and performance. I’ve never written a database or a high-performance messaging system, and other than an academic interest, I’m not particularly knowledgeable about how they work.</p>



<p>I’m a frontend developer. GraphQL makes my life easy.</p>



<p>This post caught my eye because it seemed like a great way to analyze how people familiar with other kinds of APIs might respond to an initial look at GraphQL, and the misconceptions that might make it seem like an overly complex solution to a simple problem. But, as anyone who has spent a lot of time working with APIs will know, getting the right data to the right place (with any technology) can be anything but simple.</p>



<h2 class="wp-block-heading" id="1cd8"><a href="#graphql-is-a-query-language-like-sql" aria-hidden="true" class="aal_anchor" id="graphql-is-a-query-language-like-sql"><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>GraphQL is a query language, like SQL?</h2>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>GraphQL seems like the numerous TEXTAREAS I’ve deployed behind the firewall to allow trusted users to write SQL to get at the database — which is just poking a hole, not very evolutionary at all.</p></blockquote>



<p>While GraphQL looks like a query language at first, I think its name might be one of the things that gets people off on the wrong foot. GraphQL is not at all like SQL:</p>



<ul class="wp-block-list"><li>You don’t connect GraphQL directly to your backend or database. It’s an API layer, just like REST.</li><li>GraphQL intentionally doesn’t include built-in filtering, sorting, computations, or joins. You carefully design all of those yourself to fit the needs of the API consumer, just like REST.</li><li>GraphQL can be layered over multiple backends and databases, without the client being aware of where the data is coming from, just like REST.</li></ul>



<p>So GraphQL is a “query language” just like URLs are the “query language” of REST—it’s a contract that describes how to tell the API server what you’re looking for.</p>



<h2 class="wp-block-heading" id="e11f"><a href="#graphql-is-too-hard" aria-hidden="true" class="aal_anchor" id="graphql-is-too-hard"><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>GraphQL is too hard?</h2>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>It seems like you would attract 5 very technical API developers who would love it, but then exclude 5 non-technical users.</p></blockquote>



<p>This is a very real concern whenever a new technology is introduced. Is this going to make stuff more complicated for everyone who isn’t in the know? Will it exclude people who don’t care about the finer points of graphs, nodes, and edges?</p>



<p>But the best part about GraphQL is exactly this point: It’s built from the ground up to make life easy for people who are trying to query it.</p>



<ul class="wp-block-list"><li>It’s the only API platform that comes with a fully-featured data explorer out of the box (<a href="https://github.com/graphql/graphiql" target="_blank" rel="noreferrer noopener">GraphiQL</a>). People who use technologies like Firebase are often excited about how easy it is to explore their data directly from a dashboard. GraphQL is intentionally designed to enable tools like this, and GraphiQL is only the beginning.</li><li>Even though you can easily send a GraphQL query with&nbsp;<em>curl —&nbsp;</em>no special tools needed — you don’t have to worry about the details of HTTP. Once you learn the language of GraphQL, you’re done. People often like to say that REST is “just HTTP”, but it turns out HTTP is not that simple — you have to know which method (GET? POST? PUT? PATCH? DELETE? can I even call these from my browser?) to use for each endpoint. You need to have some way of identifying which query parameters can be passed in the URL, and how they need to be serialized to avoid errors with special characters.</li><li>GraphQL always returns what you expect. Depending on how principled the REST API you’re calling is, it could give you back basically anything for every request. In GraphQL, you’ll never be surprised by what you get back from the server.</li></ul>



<p>There are a whole lot of companies out there with a whole business model of helping you describe your REST API and make it easier to get started with, because the base technology doesn’t provide these tools. To me, that’s the ultimate mark of a great tool — the language you use to interact with GraphQL is something you actually want to use directly (once you get used to it, of course), rather than immediately hiding it under layers of client abstractions.</p>



<p>If you want to try out writing some GraphQL queries, check out&nbsp;<a href="https://learngraphql.com/" target="_blank" rel="noreferrer noopener">https://learngraphql.com/</a>.</p>



<h2 class="wp-block-heading" id="d6fa"><a href="#this-is-just-the-beginning" aria-hidden="true" class="aal_anchor" id="this-is-just-the-beginning"><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>This is just the beginning</h2>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>GraphQL feels like a quick fix to me and not one that looks to the future</p></blockquote>



<p>The most exciting thing to me is that GraphQL has been publicly available for barely more than a year, and already a huge number of people I respect for their technical abilities and design thinking are trying to figure out ways to add it to their architecture. Part of the reason is that Facebook has been using it internally since 2012, so they’ve had a lot of time to iron out the kinks.</p>



<p>We’ve only scratched the surface of where it can go and how its clean, standardized way of describing and querying APIs can revolutionize data sharing on the internet. We’ve only seen one or two great tools extracted from this absolute gold mine of possibilities. Where REST was an ad-hoc philosophy that spawned many incompatible ways to describe, build, and consume APIs, GraphQL is a well-specified standard designed from the ground up to enable people to easily describe, understand, and retrieve their data with a shared language.</p>



<p>That’s why we spend so much time at&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Apollo</a>&nbsp;doing our best to bring GraphQL to its full potential. I hope the above has started to convince any newcomers to the technology that it’s not all just a waste of time.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="937" height="493" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_sZYgCHu2Tx4RS9USCQFuZg.png" alt="" class="wp-image-319" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_sZYgCHu2Tx4RS9USCQFuZg.png 937w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sZYgCHu2Tx4RS9USCQFuZg-300x158.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sZYgCHu2Tx4RS9USCQFuZg-768x404.png 768w" sizes="auto, (max-width: 937px) 100vw, 937px" /></figure>


GraphQL: The next generation of API design


<p>Yesterday, version 0.7 of&nbsp;<a href="https://github.com/graphql/graphql-js" target="_blank" rel="noreferrer noopener">GraphQL.js</a>&nbsp;was released, and it contains a lot of exciting improvements, including new features for the schema language, an update to default resolve functions, and utilities for constructing and handling GraphQL documents. In this post I’ll cover:</p>



<ul class="wp-block-list"><li>New features — how, when and why to use them</li><li>Breaking changes — how and if they impact you</li><li>Fixes — what was fixed and why</li></ul>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="978" height="508" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_kq_hWXFncvmcP2h7qzdIag.png" alt="" class="wp-image-316" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_kq_hWXFncvmcP2h7qzdIag.png 978w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_kq_hWXFncvmcP2h7qzdIag-300x156.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_kq_hWXFncvmcP2h7qzdIag-768x399.png 768w" sizes="auto, (max-width: 978px) 100vw, 978px" /></figure>



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



<p>Let’s start with the most exciting of the bunch!</p>



<h2 class="wp-block-heading" id="9e28"><a href="#new-schema-language-improvements-descriptions-more" aria-hidden="true" class="aal_anchor" id="new-schema-language-improvements-descriptions-more"><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>New — Schema language improvements: descriptions + more</h2>



<p>Adding descriptions to the schema language was one of the most requested features in GraphQL.js since support for the schema language itself was added in 0.5.0, and finally it’s out!</p>



<p>With 0.7, you can add descriptions directly as comments in the GraphQL schema language. Any comment block that comes before a field, type or directive definition will be used as a description. Here’s an example:</p>



<pre class="wp-block-preformatted"># A small domesticated carnivorous mammal with soft fur<br># See [Wikipedia entry for cat](<a href="https://en.wikipedia.org/wiki/Cat" target="_blank" rel="noreferrer noopener">https://en.wikipedia.org/wiki/Cat</a>)<br>type Cat extends Mammal {<br>  name: String<br>  meows: Boolean<br>  purrs: Boolean<br>  scratches: Boolean<br>}</pre>



<p>Markdown syntax in descriptions is explicitly supported in the GraphQL spec, so tools like GraphiQL are built to work with it!</p>



<p>While the GraphQL schema language itself isn’t part of the of the&nbsp;<a href="https://facebook.github.io/graphql/" target="_blank" rel="noreferrer noopener">official spec</a>&nbsp;yet, it’s proving to be so useful that the plan is to include it there soon. There are already many libraries, such as&nbsp;<a href="https://github.com/apollostack/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools</a>, that use it for things like mocking and generating schemas.</p>



<p>Version 0.7 added other features to make using the schema language even more convenient:</p>



<ul class="wp-block-list"><li>Schemas returned by&nbsp;<em>buildASTSchema&nbsp;</em>are now executable. (<strong>Caveat</strong>: unions and interfaces are not supported out of the box, nor is parsing and serialization of scalar types, but GraphQL.js provides a useful error message in those cases.)</li><li>The new&nbsp;<em>buildSchema</em>&nbsp;utility function makes creating an executable schema object from the schema language a tiny bit more convenient.</li></ul>



<p>Taken together, all these changes make a pretty compelling case for using the GraphQL schema language.</p>



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



<p>Until 0.7, there was no official recommendation for what to name your root types, so people chose different alternatives: Query, RootQuery, QueryRootType, etc. GraphQL.js 0.7 is more opinionated here; it prefers:&nbsp;<strong>Query</strong>,&nbsp;<strong>Mutation</strong>&nbsp;and&nbsp;<strong>Subscription</strong>. This is not a breaking change, so you can still continue to name your root types differently, but if you use the Query, Mutation and Subscription, you will no longer need to specify the names of the root types when creating a shorthand schema:</p>



<pre class="wp-block-preformatted">type Query {<br>  aString: String<br>}# The following is now unnecessary if your root type is called Query<br>schema {<br>  query: Query<br>}</pre>



<p>Even though it’s not required, I strongly recommend using the standard names for Query, Mutation and Subscription root types from now on.</p>



<h2 class="wp-block-heading" id="e56d"><a href="#breaking-default-resolvers-now-get-args-and-context" aria-hidden="true" class="aal_anchor" id="breaking-default-resolvers-now-get-args-and-context"><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>Breaking — Default resolvers now get args and context</h2>



<p>Until 0.7.0, the default resolve function in GraphQL did not pass along arguments and context, which meant that for all but the most trivial use-cases you had to define a resolve function.</p>



<p>With 0.7, you can now define more complex behavior directly on your JavaScript objects and execute GraphQL queries directly on a schema without having to define resolvers. For example you could do this:</p>



<pre class="wp-block-preformatted">const query = `query {<br>  addOrSubtractTwo(num: 10)<br>}`;const schema = buildSchema(`<br>  type Query {<br>    addOrSubtractTwo: Int<br>  }<br>`);const rootObject = {<br>  addOrSubtractTwo({ num }, context){<br>    return num + 2 * context.polarity;<br>  }<br>};const result = graphql(<br>  schema,<br>  query,<br>  rootObject,<br>  { polarity: -1 },<br>);// result is now { data: { addOrSubtractTwo: 8 } }</pre>



<p>This is a breaking change because until now the default resolve function would not pass through arguments and context. However, unless you specifically programmed your function to behave differently when it gets arguments vs when it gets no arguments, you should be fine.</p>



<h2 class="wp-block-heading" id="2e41"><a href="#breaking-better-graphqlerrors" aria-hidden="true" class="aal_anchor" id="breaking-better-graphqlerrors"><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>Breaking</strong> — Better GraphQLErrors</h2>



<p>In 0.7 there are improvements to GraphQLError that get rid of unexpected behavior arising due to the special treatment of Error on many platforms. This is, strictly speaking, an improvement. The breaking change won’t affect you unless you called the GraphQLError constructor explicitly in your code, in which case you should check the&nbsp;<a href="https://github.com/graphql/graphql-js/commit/8df7894c8974bd19c600ad05df9d42ed3def3e65#diff-ec43eb1480c36bfa8361782be0ba7066R73" target="_blank" rel="noreferrer noopener">diff</a>&nbsp;and adjust the argument order to make sure your code still works. You may also have to update some of your test code if you relied on e.stack, because GraphQLError now provides stack traces in some cases where it didn’t before, and it no longer writes the message to the stack property when stack is missing.</p>



<p>A change that was already made in 0.6, but that has gotten relatively little notice so far, is that GraphQLError now includes a&nbsp;<strong>path</strong>&nbsp;property, which lets you correlate each error with the corresponding field in the response. That’s especially useful if you want your client to provide useful error messages to the user, or adjust its caching behavior based on whether a field errored or not. However, the default&nbsp;<em>formatError&nbsp;</em>function still filters it out, so if you want to make use of&nbsp;<strong>path</strong>&nbsp;on the client, you have to override the default function by passing the right&nbsp;<em>formatError&nbsp;</em>option to&nbsp;<a href="https://github.com/graphql/express-graphql" target="_blank" rel="noreferrer noopener">express-graphql</a>&nbsp;or&nbsp;<a href="https://github.com/apollostack/apollo-server" target="_blank" rel="noreferrer noopener">apollo-server</a>:</p>



<pre class="wp-block-preformatted">formatError: e =&gt; ({ <br>  message: e.message,<br>  locations: e.locations,<br>  path: e.path<br>}),</pre>



<h2 class="wp-block-heading" id="247c"><a href="#fixes-directives-in-extendschema-and-error-message" aria-hidden="true" class="aal_anchor" id="fixes-directives-in-extendschema-and-error-message"><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>Fixes — Directives in extendSchema and error.message</h2>



<p>Version 0.7 also has a fix for an issue with errors, and adds functionality that was missing in extendSchema:</p>



<ul class="wp-block-list"><li><em>GraphQLError</em>&nbsp;no longer write messages to the stack property of the error, which preserves the original stack and improves compatibility with tools that expect the stack to have a specific format.</li><li>The&nbsp;<em>extendSchema</em>&nbsp;function now supports extending a schema with new directives.</li></ul>



<h2 class="wp-block-heading" id="84fe"><a href="#new-utility-separateoperations" aria-hidden="true" class="aal_anchor" id="new-utility-separateoperations"><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>New utility — separateOperations</h2>



<p>Last but not least, the new&nbsp;<em>separateOperations&nbsp;</em>utility function gives us another glimpse of what Facebook’s internal GraphQL setup looks like.</p>



<p><em>separateOperations</em>&nbsp;takes in a GraphQL document with (potentially) many operation definitions and fragments, and returns an array of documents, which each contain one operation definition and all the fragments used in that operation. Operations are things like queries, mutations and subscriptions.</p>



<p>How and why does Facebook use&nbsp;<em>separateOperations</em>? In their own&nbsp;<a href="https://github.com/graphql/graphql-js/pull/456" target="_blank" rel="noreferrer noopener">words</a>:</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>A typical task using GraphQL at Facebook looks something like:</p><p>1. Load and parse all .graphql files which may contain operations or fragments.</p><p>2. Use concatAST to produce one AST that contains all operations and fragments.</p><p>3. Separate this all-encompasing AST into individual ASTs that represent each operation which could be sent to the server in isolation.</p></blockquote>



<p><em>separateOperations&nbsp;</em>is for the third step, and it lets Facebook cache the many operations separately, instead of just caching one huge document that contains all of them.</p>



<h2 class="wp-block-heading" id="a8b2"><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>This concludes our not-so-little tour of what’s changed in GraphQL.js 0.7. If you want to know the details, you can always check the excellent&nbsp;<a href="https://github.com/graphql/graphql-js/releases/tag/v0.7.0" target="_blank" rel="noreferrer noopener">release notes</a>. A huge thanks to&nbsp;<a href="https://medium.com/u/d9b1a61823fa?source=post_page-----921e75dd7fd1----------------------" target="_blank" rel="noreferrer noopener">Lee Byron</a>,&nbsp;<a href="https://medium.com/u/236f88713399?source=post_page-----921e75dd7fd1----------------------" target="_blank" rel="noreferrer noopener">Kevin Lacker</a>,&nbsp;<a href="https://medium.com/u/3e6b69951eef?source=post_page-----921e75dd7fd1----------------------" target="_blank" rel="noreferrer noopener">Robert Zhu</a>&nbsp;and&nbsp;<a href="https://medium.com/u/8422e2f8a83e?source=post_page-----921e75dd7fd1----------------------" target="_blank" rel="noreferrer noopener">Rylan Hawkins</a>&nbsp;who all worked on this great release!</p>



<p>Personally, I’m really excited about all these changes and new features. The pace of development in the GraphQL ecosystem is accelerating really significantly. For an open-source project that’s barely a year old, GraphQL already has an incredible amount of traction and a remarkably vibrant community, and it’s only getting better!</p>


All you need to know about GraphQL.js 0.7


<figure class="wp-block-image"><img decoding="async" src="https://miro.medium.com/max/652/1*ApjDc-faW5qZGqhybhHXCQ.png" alt=""/></figure>



<p>Today, we’re proud to announce the release of&nbsp;<a href="https://github.com/apollostack/apollo-server" target="_blank" rel="noreferrer noopener">Apollo Server</a>&nbsp;0.2!</p>



<p>Apollo Server is a&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL server</a>&nbsp;for JavaScript, built by an open-source community of GraphQL enthusiasts. It uses GraphQL.js and works with all major Node.js server frameworks — Express, Connect, hapi and Koa.</p>



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



<p>The new Apollo Server is a major upgrade from version 0.1.0. Over the last few weeks, we re-wrote it from the ground up to be more simple, more modular and just generally more awesome. Our main goal was to build a fully-featured, yet simple GraphQL server that is production-ready and can evolve with the needs of the community.</p>



<p>Here’s a quick summary of what’s new compared to version 0.1 — more details below:</p>



<ul class="wp-block-list"><li>Added support for&nbsp;<a href="http://hapijs.com/" target="_blank" rel="noreferrer noopener">hapi</a>&nbsp;(thanks to&nbsp;<a href="https://medium.com/u/565e3f1289e1?source=post_page-----7e06b0a8fdb1----------------------" target="_blank" rel="noreferrer noopener">Nick Nance</a>!)</li><li>Added support for&nbsp;<a href="http://koajs.com/" target="_blank" rel="noreferrer noopener">Koa</a>&nbsp;(thanks to&nbsp;<a href="https://github.com/HriBB" target="_blank" rel="noreferrer noopener">@HriBB</a>!)</li><li>Rewritten from scratch in&nbsp;<a href="https://www.typescriptlang.org/" target="_blank" rel="noreferrer noopener">TypeScript</a></li><li>Schema generation was moved to a separate repo —&nbsp;<a href="https://github.com/apollostack/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools</a></li><li><a href="https://github.com/graphql/graphiql" target="_blank" rel="noreferrer noopener">GraphiQL</a>&nbsp;is served from a separate path</li><li>Now exposes the core functions to allow for easy extension</li><li>Added built-in support for&nbsp;<a href="https://medium.com/apollo-stack/query-batching-in-apollo-63acfd859862" target="_blank" rel="noreferrer noopener">query batching</a></li><li>Added built-in support for stored queries</li></ul>



<p>In addition to all of that, we also&nbsp;<a href="http://docs.apollostack.com/apollo-server/" target="_blank" rel="noreferrer noopener">updated the docs</a>&nbsp;and added many more code snippets to make it even easier to get started.</p>



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



<p>The first version of Apollo Server was little more than a set of tools for generating GraphQL schemas, wrapped around express-graphql. While that was quite useful for demo purposes, it became clear that bundling a GraphQL server together with a set of tools for generating schemas wasn’t the right approach in the long term. In addition to splitting the schema tools into a separate project, we also wanted add some more usage/production oriented features: hapi and Koa support, batching and query whitelisting. Finally, we also wanted to make the project more maintainable by using TypeScript. That’s why we decided to re-write Apollo Server from the ground up.</p>



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



<h3 class="wp-block-heading" id="866f"><a href="#1-support-for-hapi-and-koa" aria-hidden="true" class="aal_anchor" id="1-support-for-hapi-and-koa"><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. Support for hapi and Koa</h3>



<p>Everyone has their preference when it comes to Node.js server frameworks. Now that Apollo Server supports Express, Connect, hapi and Koa, the choice is completely up to you.</p>



<p>The following code snippet shows how to use Apollo Server with hapi:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import hapi from &#039;hapi&#039;;
import graphql from &#039;graphql&#039;;
import { ApolloHAPI } from &#039;apollo-server&#039;;

const myGraphQLSchema = new graphql.GraphQLSchema({
    // define your schema in GraphQL.js syntax here ...
});

const server = new hapi.Server();

const HOST = &#039;localhost&#039;;
const PORT = 3000;

server.connection({
    host: HOST,
    port: PORT,
});

server.register({
    register: new ApolloHAPI(),
    options: { schema: myGraphQLSchema },
    routes: { prefix: &#039;/graphql&#039; },</code></pre>



<h3 class="wp-block-heading" id="43fa"><a href="#2-typings" aria-hidden="true" class="aal_anchor" id="2-typings"><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. Typings</h3>



<p>With the complete re-write in TypeScript, you now get the benefits of having typings for Apollo Server, which makes it really nice to use in your other TypeScript projects. For a complete example, check out the&nbsp;<a href="https://github.com/nnance/swapi-apollo" target="_blank" rel="noreferrer noopener">swapi-apollo</a>&nbsp;project by Nick Nance.</p>



<h3 class="wp-block-heading" id="f09e"><a href="#3-simplified-modular-codebase" aria-hidden="true" class="aal_anchor" id="3-simplified-modular-codebase"><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. Simplified &amp; modular codebase</h3>



<p>To make Apollo Server easy to use and modify, we focused on simplicity and modularity. First, we made a small core, which is used by the Express, Connect, hapi and Koa integrations. To keep the core as simple as possible, we split other functionality, such as GraphiQL and stored queries, into a separate module. Finally, we removed support for defining GraphQL schemas in schema language and moved it to an entirely separate npm module —&nbsp;<a href="https://github.com/apollostack/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools</a>.</p>



<p>Apollo Server exposes the core functionality and modules, making it really easy to add functionality or extend it for use in other frameworks.</p>



<h3 class="wp-block-heading" id="ecca"><a href="#4-query-batching" aria-hidden="true" class="aal_anchor" id="4-query-batching"><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. Query Batching</h3>



<p>Query Batching is a feature we recently introduced in Apollo Client, but it involved merging multiple queries into a single one, which made the queries sent to the server hard to read. Now that Apollo Server supports query batching as a top-level feature, you can send multiple queries in one request without merging them, which makes debugging batched queries a lot easier.</p>



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



<p>Stored Queries is a feature that lets you define and validate queries ahead of time, so that when clients make requests they only have to send the name of the query along with variables. This not only saves bandwidth, but is also a way for you to secure your server by limiting the queries that clients can make.</p>



<p>Here’s an example of how to use query whitelisting:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import express from &#039;express&#039;;
import { apolloExpress, OperationStore } from &#039;apollo-server&#039;;
import Schema from &#039;./schema&#039;;

const PORT = 3000;
const store = new OperationStore(Schema);
store.put(&#039;query testquery{ testString }&#039;);
const app = express();

const options = {
  schema: Schema,
  formatParams(params) {
    params[&#039;query&#039;] = store.get(params.operationName);
    if (!params[&#039;query&#039;]){
      throw new Error(`Only whitelisted queries are allowed. No query stored for ${params.operationName}`);
    }
    return params;
  }
};

app.use(&#039;/graphql&#039;, apolloExpress(options));

app.listen(PORT);</code></pre>



<p>Of course, you can also read the queries from a file on startup or expose an API on your server to add queries during runtime.</p>



<h3 class="wp-block-heading" id="6d36"><a href="#whats-next-for-apollo-server" aria-hidden="true" class="aal_anchor" id="whats-next-for-apollo-server"><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 Apollo Server?</h3>



<p>Apollo Server was heavily inspired by the&nbsp;<a href="https://github.com/graphql/express-graphql" target="_blank" rel="noreferrer noopener">express-graphql</a>&nbsp;reference implementation. Apart from the fact that Apollo Server supports hapi and Koa, while express-graphql does not, we also think that Apollo Server is more modular and easier to understand, making it easier for contributors to add new features.</p>



<p>Rather than seeing Apollo Server and express-graphql as competing alternatives, we think that they both have distinct roles in the GraphQL ecosystem. While express-graphql is intended to be a simple reference implementation of currently established standards, Apollo Server is built for production users and can evolve quickly with the needs of the community. This means it can serve as a proving ground for new concepts and ideas in the GraphQL ecosystem. Over time, express-graphql could adopt those features of Apollo Server which have proven themselves in practice.</p>



<p>The features in this release were driven by input and contributions from several community members interested in improving the production-readiness of GraphQL. Going forward, we will keep improving Apollo Server based on what the community of production GraphQL users need.</p>



<p>If you’re using GraphQL on Node.js, check out&nbsp;<a href="https://github.com/apollostack/apollo-server" target="_blank" rel="noreferrer noopener">Apollo Server</a>&nbsp;and join the contributor community by filing an issue or submitting a pull request!</p>



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



<p><em>Many thanks to&nbsp;</em><a href="https://medium.com/u/565e3f1289e1?source=post_page-----7e06b0a8fdb1----------------------" target="_blank" rel="noreferrer noopener"><em>Nick Nance</em></a><em>,&nbsp;</em><a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----7e06b0a8fdb1----------------------" target="_blank" rel="noreferrer noopener"><em>James Baxley III</em></a><em>,&nbsp;</em><a href="https://medium.com/u/6ca780f916b8?source=post_page-----7e06b0a8fdb1----------------------" target="_blank" rel="noreferrer noopener"><em>Ian MacLeod</em></a><em>,&nbsp;</em><a href="https://github.com/HriBB" target="_blank" rel="noreferrer noopener"><em>@HriBB</em></a><em>&nbsp;for their contributions to Apollo Server 0.2!</em></p>


Apollo Server 0.2: GraphQL with Express, Connect, hapi or Koa


<p><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>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>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>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>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>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>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>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>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>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>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>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><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><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>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>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>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>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>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>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>Here’s an example of what it could look like in actual code.</p>



<p>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>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>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>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>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><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>Once I was reasonably happy with the structure of my GraphQL server, I was ready to optimize performance.</p>



<p>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><strong>The short answer is</strong>: you don’t. Use caching and batching instead.</p>



<p><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>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>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>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>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>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>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>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>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>


How to structure GraphQL server code


<p>By now you’ve almost certainly heard of&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL</a>, an open-source data query language and runtime. There’s been a lot of buzz about it lately — at&nbsp;<a href="https://www.react-europe.org/" target="_blank" rel="noreferrer noopener">React Europe</a>, which took place in Paris last week, there were&nbsp;<a href="https://www.youtube.com/watch?v=etax3aEe2dA" target="_blank" rel="noreferrer noopener">three</a>&nbsp;<a href="https://www.youtube.com/watch?v=ViXL0YQnioU" target="_blank" rel="noreferrer noopener">full</a>&nbsp;<a href="https://www.youtube.com/watch?v=z5rz3saDPJ8" target="_blank" rel="noreferrer noopener">talks</a>&nbsp;about GraphQL. After reading this post, you will know why.</p>



<h2 class="wp-block-heading" id="4d93"><a href="#1-youre-already-using-it" aria-hidden="true" class="aal_anchor" id="1-youre-already-using-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>1. You’re already using it.</h2>



<p>In case this is the first time you’re hearing about GraphQL, here’s an interesting fact: You’ve been using it every day for the last few years. Facebook has more than 1 billion daily active users, and GraphQL is fundamental to how Facebook works. Using Facebook means using GraphQL.</p>



<p>Facebook has been using GraphQL since 2012 — well before it was open-sourced in July of last year. Since then, there’s been a flurry of activity, and the open-source ecosystem around GraphQL has grown rapidly.</p>



<h2 class="wp-block-heading" id="fe4e"><a href="#2-graphql-solves-real-problems-and-people-are-taking-notice" aria-hidden="true" class="aal_anchor" id="2-graphql-solves-real-problems-and-people-are-taking-notice"><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. GraphQL solves real problems, and people are taking notice.</h2>



<p>It’s not just React developers who are getting excited about GraphQL. Angular, iOS and Android developers are equally interested in what GraphQL has to offer. Its popularity is rapidly growing, and for a good reason: GraphQL has solutions for some very real problems that developers grapple with every day. That’s why companies like&nbsp;<strong>Twitter</strong>,&nbsp;<a href="https://twitter.com/madhavn/status/725880367970848768" target="_blank" rel="noreferrer noopener"><strong>Intuit</strong></a>&nbsp;and&nbsp;<a href="https://www.drupal.org/project/graphql" target="_blank" rel="noreferrer noopener"><strong>Drupal</strong></a>&nbsp;are adopting it.</p>



<p><a rel="noreferrer noopener" href="https://get.fabric.io/" target="_blank">Fabric</a>, Twitter’s mobile development platform, just announced that they are using GraphQL:</p>



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



<p>Since we started building&nbsp;<a href="http://www.apollostack.com/" target="_blank" rel="noreferrer noopener">Apollo</a>, an open-source GraphQL data stack, we’ve been approached almost daily by companies who want to adopt GraphQL for building a new product, or even rewrite their entire production infrastructure to use GraphQL.</p>



<p>These companies are very diverse, but they have one thing in common — they all have at least one of the following:</p>



<ul class="wp-block-list"><li>They have more than one client (e.g. web + iOS)</li><li>They have a mobile client and care about latency and bandwidth</li><li>They are moving to a microservices architecture</li><li>Their REST API has gotten so complicated that it’s a significant drag on product development.</li><li>They want to decouple frontends and backends to speed up development</li></ul>



<p>Companies turn to GraphQL because they realize that REST can’t help them solve these problems, but GraphQL can. Which brings me to my next point…</p>



<h2 class="wp-block-heading" id="60e9"><a href="#3-rest-is-not-the-answer" aria-hidden="true" class="aal_anchor" id="3-rest-is-not-the-answer"><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. REST is not the answer.</h2>



<p>Here’s the difference between REST and GraphQL in a nutshell:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="642" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA-1024x642.png" alt="" class="wp-image-223" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA-1024x642.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA-300x188.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA-768x481.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA-1536x963.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA-1200x752.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aE40t8NcePLKWKjUx-8IgA.png 1742w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Where REST has only an ad-hoc approach, GraphQL has a clean layer of abstraction</figcaption></figure>



<p>GraphQL is the clean layer of abstraction between servers and clients that an ad-hoc REST approach will never be able to provide.</p>



<p>This post isn’t going to go into more detail about how GraphQL compares to REST, but if you’re interested in digging deeper, we’ve written several of&nbsp;<a href="https://medium.com/apollo-stack/the-basics-of-graphql-in-5-links-9e1dc4cac055" target="_blank" rel="noreferrer noopener">blog</a>&nbsp;<a href="https://medium.com/apollo-stack/how-do-i-graphql-2fcabfc94a01" target="_blank" rel="noreferrer noopener">posts</a>&nbsp;<a href="https://medium.com/apollo-stack/graphql-explained-5844742f195e" target="_blank" rel="noreferrer noopener">about</a>&nbsp;<a href="https://medium.com/apollo-stack/power-tools-for-your-api-42529706ae78" target="_blank" rel="noreferrer noopener">it</a>.</p>



<p>Don’t take it from me. Ask any of these people:</p>



<ul class="wp-block-list"><li><a href="https://blog.jacobwgillespie.com/from-rest-to-graphql-b4e95e94c26b" target="_blank" rel="noreferrer noopener">From REST to GraphQL</a>&nbsp;by&nbsp;<a href="https://medium.com/u/cae5dd810cc0?source=post_page-----3bec28193807----------------------" target="_blank" rel="noreferrer noopener">Jacob Gillespie</a></li><li><a href="https://www.youtube.com/watch?v=S0s935RKKB4" target="_blank" rel="noreferrer noopener">GraphQL at The Financial Times</a>&nbsp;by Victor Charypar</li><li><a href="https://medium.com/apollo-stack/the-business-case-for-graphql-cc7a2b93148d" target="_blank" rel="noreferrer noopener">The Business Case for GraphQL</a>&nbsp;by&nbsp;<a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----3bec28193807----------------------" target="_blank" rel="noreferrer noopener">James Baxley III</a></li><li><a href="https://voice.kadira.io/adopting-graphql-2f00dfe0fda2" target="_blank" rel="noreferrer noopener">Adopting GraphQL</a>&nbsp;by&nbsp;<a href="https://medium.com/u/233a53961f2f?source=post_page-----3bec28193807----------------------" target="_blank" rel="noreferrer noopener">Arunoda Susiripala</a></li></ul>



<p>There are many more examples out there if you care to look for them. Twitter, Intuit, and Drupal are only the beginning (and in Drupal’s case, their GraphQL module is&nbsp;<a href="http://buytaert.net/advancing-drupal-web-services" target="_blank" rel="noreferrer noopener">only the beginning</a>). I could tell you the names of at least a dozen more well-known companies who just haven’t publicly announced their GraphQL use yet. There’s no doubt about it, GraphQL is the future.</p>



<p>You might be thinking, “That’s great, but why should I care?”</p>



<h2 class="wp-block-heading" id="e06f"><a href="#4-graphql-is-great-news-for-developers" aria-hidden="true" class="aal_anchor" id="4-graphql-is-great-news-for-developers"><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. GraphQL is great news for developers.</h2>



<p>GraphQL brings order to the chaos:</p>



<ul class="wp-block-list"><li>Clean API between backends and frontends</li><li>Less communication overhead and fewer meetings</li><li>No more time spent writing API documentation</li><li>No more time spent trying to figure out an API</li><li>Great tooling for your API</li></ul>



<p>With GraphQL, it takes literally 5 minutes for a new engineer to learn how to use your API. And that includes the time they need to understand how to write basic GraphQL queries.</p>



<p>So whether you’re a React, Angular, Ember, iOS or Android developer: take some time to learn about GraphQL, use it in your next project and try to convince your colleagues or your boss to start adopting it. You won’t regret it.</p>



<p>The best news is — you’re not alone! There are many devs who are just discovering GraphQL, and they’re finding a very friendly and supportive community out there of other newcomers. Some are in our&nbsp;<a href="http://slack.apollostack.com/" target="_blank" rel="noreferrer noopener">Slack channel</a>, and others are joining a very active group of users and contributors in the&nbsp;<a href="https://github.com/apollostack" target="_blank" rel="noreferrer noopener">Apollo</a>&nbsp;and&nbsp;<a href="https://github.com/graphql" target="_blank" rel="noreferrer noopener">GraphQL</a>&nbsp;GitHub organizations.</p>



<p>And if you run into a member of the REST police or a professional curmudgeon, just remember this:</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>A new scientific truth does not triumph by convincing its opponents and making them see the light, but rather because its opponents eventually die out, and a new generation grows up that is familiar with it.</strong></p><p>— Max Planck</p></blockquote>


Why GraphQL is the future


<p>As the team at&nbsp;<a href="http://www.apollostack.com/" target="_blank" rel="noreferrer noopener">Apollo Stack</a>&nbsp;has been working with&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL</a>&nbsp;to build a data stack for modern applications, we’ve run into more and more people who are excited about what GraphQL has to offer — whether they’re using it in their products or extending it with tooling of their own.</p>



<p>When we set out to find all the major GraphQL-based open source projects out there, we couldn’t even get them all on the same slide. Here are just some of them:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="576" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-1024x576.jpg" alt="" class="wp-image-219" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-1024x576.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-300x169.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-768x432.jpg 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-1536x864.jpg 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-2048x1152.jpg 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-1200x675.jpg 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_KagcukjRWEc8-C10s_jptg-1980x1114.jpg 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>But even with all this momentum, we hadn’t seen many opportunities for all these people to get in a room and talk about where GraphQL and the ecosystem around it is going. So we decided to host one ourselves.</p>



<p>We organized our very first&nbsp;<a href="http://www.meetup.com/GraphQL-SF/events/231107183/" target="_blank" rel="noreferrer noopener">GraphQL-only meetup</a>, and in just a couple of days got people from some of the most exiting GraphQL projects on board to speak. Joining&nbsp;<a href="https://twitter.com/helferjs" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>&nbsp;and&nbsp;<a href="https://twitter.com/stubailo" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;from the Apollo team were&nbsp;<a href="https://medium.com/u/d9b1a61823fa?source=post_page-----89846d9bb29e----------------------" target="_blank" rel="noreferrer noopener">Lee Byron</a>&nbsp;and&nbsp;<a href="https://medium.com/u/b4e014dacf1e?source=post_page-----89846d9bb29e----------------------" target="_blank" rel="noreferrer noopener">Joseph Savona</a>&nbsp;from Facebook’s GraphQL and Relay teams,&nbsp;<a href="https://medium.com/u/df9da892406d?source=post_page-----89846d9bb29e----------------------" target="_blank" rel="noreferrer noopener">Syrus Akbary</a>&nbsp;from Graphene, and&nbsp;<a href="https://medium.com/u/d28ccbf19c49?source=post_page-----89846d9bb29e----------------------" target="_blank" rel="noreferrer noopener">Clay Allsopp</a>&nbsp;from GraphQLHub.</p>



<p>Not only did we get a look into where each individual project is going, but we got everyone together afterwards for a panel to discuss the past, present and future of GraphQL’s community.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="683" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg-1024x683.jpg" alt="" class="wp-image-220" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg-1024x683.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg-300x200.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg-768x512.jpg 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg-1536x1025.jpg 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg-1200x801.jpg 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rSBDLTSADZ4t7xMtVCg5mg.jpg 1920w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Panel Discussion</figcaption></figure>



<p>Sound awesome? Check out the full videos below.</p>



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



<h2 class="wp-block-heading" id="87cd"><a href="#graphene-making-graphql-easier" aria-hidden="true" class="aal_anchor" id="graphene-making-graphql-easier"><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>Graphene: Making GraphQL Easier</h2>



<p>First up was a brief introduction to the GraphQL ecosystem. The first talk came from Syrus Akbary, who created <a rel="noreferrer noopener" href="http://graphene-python.org/" target="_blank">Graphene</a>, a library that lets you use GraphQL in Python. He dove into some recent feature updates to Graphene (including Google App Engine support and middleware) and explored what the community can do to make GraphQL better.</p>



<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="Graphene: Making GraphQL Easier - Syrus Akbary" width="580" height="326" src="https://www.youtube.com/embed/ND9GWSkbUGM?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



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



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



<p>Sashko followed with a talk about how Apollo Client makes it easy to build a full stack app using GraphQL. To demonstrate this, he showed how he used GraphQL, <a rel="noreferrer noopener" href="https://github.com/apollostack/apollo-client" target="_blank">Apollo Client</a> and Redux to build <a rel="noreferrer noopener" href="https://github.com/apollostack/GitHunt" target="_blank">GitHunt</a>, an example app letting you vote for your favorite repositories.</p>



<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="Apollo Client: Put GraphQL data in your UI - Sashko Stubailo" width="580" height="326" src="https://www.youtube.com/embed/u1E0CbGeICo?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



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



<h2 class="wp-block-heading" id="481b"><a href="#whats-next-for-relay-js" aria-hidden="true" class="aal_anchor" id="whats-next-for-relay-js"><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 Relay.js</h2>



<p>Next, Joe Savona dove into <a rel="noreferrer noopener" href="https://facebook.github.io/relay/" target="_blank">Relay.js</a>, Facebook’s JavaScript framework that leverages GraphQL to handle data requirements and mutations. He focused on use cases Relay is targeting now and in the future: fetching data, pagination, mutations, and performance.</p>



<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="What&#039;s Next for Relay.js - Joe Savona" width="580" height="326" src="https://www.youtube.com/embed/7TA4T2TJQx0?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



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



<h2 class="wp-block-heading" id="8b0f"><a href="#evolving-graphql-hub" aria-hidden="true" class="aal_anchor" id="evolving-graphql-hub"><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>Evolving GraphQL Hub</h2>



<p>For the last talk Clay Alsopp spoke about <a rel="noreferrer noopener" href="https://www.graphqlhub.com/" target="_blank">GraphQLHub</a>, a website (and npm module) he created that lets you query popular APIs with GraphQL. He talked about how he’s taken a more idiomatic approach to GraphQL over the course of building GraphQLHub.</p>



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



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



<h2 class="wp-block-heading" id="ad0b"><a href="#panel-discussion-with-lee-byron-graphql-in-2016" aria-hidden="true" class="aal_anchor" id="panel-discussion-with-lee-byron-graphql-in-2016"><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>Panel Discussion with Lee Byron: GraphQL in 2016</h2>



<p>In the panel, we got an inside look into the motivation behind each speaker’s involvement with GraphQL and the problems they are looking to solve with their respective projects. Special guest Lee Byron, who helps maintain the GraphQL specification and reference implementation at Facebook, talked about GraphQL’s development, design, and (purposeful) limitations, as well as areas the community can contribute.</p>



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



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



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



<p>If you’d like to dive even deeper into GraphQL, the speakers mentioned some great resources you can use to learn more:</p>



<ul class="wp-block-list"><li><a href="https://www.youtube.com/watch?v=UBGzsb2UkeY" target="_blank" rel="noreferrer noopener"><strong>Zero to GraphQL in 30 Minutes</strong></a>&nbsp;—a talk from Relay developer Steven Luscher (and accompanying&nbsp;<a href="https://github.com/steveluscher/zero-to-graphql" target="_blank" rel="noreferrer noopener">github repo</a>&nbsp;for examples of GraphQL endpoints in various languages and frameworks).</li><li><a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener"><strong>Building Apollo</strong></a>— Apollo Stack’s Medium publication documenting our in-depth learnings on GraphQL, including useful&nbsp;<a href="https://medium.com/apollo-stack/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener">tutorials</a>&nbsp;and&nbsp;<a href="https://medium.com/apollo-stack/graphql-explained-5844742f195e#.r8ap0x1ij" target="_blank" rel="noreferrer noopener">explanations</a>.</li><li><a href="https://learngraphql.com/" target="_blank" rel="noreferrer noopener"><strong>Learn GraphQL</strong></a>&nbsp;— a great beginner course taking you through GraphQL bases.</li><li><a href="http://makeitopen.com/" target="_blank" rel="noreferrer noopener"><strong>Make It Open</strong></a>&nbsp;— a series of tutorials on what a real app looks like if you’re using multiple projects from the GraphQL ecosystem together, based on the&nbsp;<a href="https://www.fbf8.com/" target="_blank" rel="noreferrer noopener">F8 conference</a>&nbsp;app.</li><li><a href="http://graphql.org/" target="_blank" rel="noreferrer noopener"><strong>graphql.org</strong></a>&nbsp;— GraphQL’s official website, which is always welcoming guest contributions.</li></ul>



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



<p>We enjoyed the event so much that we decided to do it again soon! Join our meetup group&nbsp;<a href="http://www.meetup.com/GraphQL-SF/" target="_blank" rel="noreferrer noopener">GraphQL San Francisco</a>&nbsp;to get updates on future events.</p>



<p><em>If you happen to be in the Toronto area, check out this&nbsp;</em><a href="http://www.meetup.com/GraphQL-Toronto/events/231125251/" target="_blank" rel="noreferrer noopener"><em>upcoming meetup</em></a><em>&nbsp;on June 15 from our friends at OK GROW!</em></p>


GraphQL in 2016: A Growing Ecosystem


<p><a href="http://graphql.org/docs/queries/" target="_blank" rel="noreferrer noopener">GraphQL’s query language</a>&nbsp;is very easy to understand. For most people, it clicks immediately and doesn’t require much explanation. Thanks to&nbsp;<a href="http://graphql.org/docs/typesystem/" target="_blank" rel="noreferrer noopener">GraphQL’s type system</a>&nbsp;and tools like&nbsp;<a href="https://medium.com/the-graphqlhub/graphiql-graphql-s-killer-app-9896242b2125" target="_blank" rel="noreferrer noopener">Graph<em>i</em>QL</a>&nbsp;— a query builder/editor for GraphQL — learning GraphQL isn’t hard at all, and its advantages over traditional RESTful APIs become obvious quite quickly.</p>



<p>Given GraphQL’s clear advantages, almost every developer I’ve talked to is eager to try it out. Here are the questions they ask:</p>



<p><strong>Question 1: Is GraphQL easy to secure?</strong></p>



<p><strong>Question 2: Is it easy to build a GraphQL server?</strong></p>



<p><strong>Question 3: Can I use GraphQL with &lt;Angular/React/Ember/Redux&gt;?</strong></p>



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



<p>The good news is: these questions are easy to answer with GraphQL!</p>



<h2 class="wp-block-heading" id="5159"><a href="#1-is-graphql-easy-to-secure" aria-hidden="true" class="aal_anchor" id="1-is-graphql-easy-to-secure"><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. Is GraphQL easy to secure?</h2>



<p>When most people hear GraphQLthey hear “query language”, and think of a query language like SQL, but for graphs. To be honest, I thought the same thing when I heard it the first time! But GraphQL is an&nbsp;<em>application</em>&nbsp;query language. What’s an application query language, you ask?&nbsp;<strong>Think of it as a structured way of making REST calls</strong>: these queries are specific to your application, not to the database that holds your data.</p>



<p>In an application query language, you ask for things like “<em>Person in age group teens</em>” and not “<em>SELECT * FROM people WHERE age &gt; 12 AND age &lt; 20</em>”. The former is how clients ask for data from the server, and the latter is how the server might fetch that data — and clients don’t need to know about that. All the client needs to know is that the application has an age group called&nbsp;<em>teens</em>.</p>



<p>So instead of exposing all the capabilities of your various backends and databases, GraphQL exposes only those that your application needs, and it controls that access tightly.&nbsp;In fact, I’d say that<strong>&nbsp;GraphQL servers are easier to secure than traditional RESTful APIs</strong>, because the schema makes it very easy to reason about what parameters clients can send in requests, how the request is fulfilled, and what data will be returned.</p>



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



<h2 class="wp-block-heading" id="d839"><a href="#2-is-it-easy-to-build-a-graphql-server" aria-hidden="true" class="aal_anchor" id="2-is-it-easy-to-build-a-graphql-server"><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. Is it easy to build a GraphQL server?</h2>



<p>GraphQL servers are really easy to build. Unfortunately, because GraphQL is catching on so quickly, the documentation available about how to build GraphQL servers isn’t as extensive as it could be. Also, the few tutorials that exist —&nbsp;<a href="https://www.youtube.com/watch?v=PHabPhgRUuU" target="_blank" rel="noreferrer noopener">my own included</a>&nbsp;— don’t do a good enough job of explaining how to think about building a GraphQL server when coming from a REST background.</p>



<p>GraphQL servers are actually very easy to build, especially compared to a traditional RESTful API. All you need to do is define a&nbsp;<strong>schema</strong>&nbsp;— essentially a directory of the data types in your application — and&nbsp;<strong>resolve functions</strong>&nbsp;that tell the server where and how to fetch the data for each data type.</p>



<p>To put things in RESTful terms, which you may be more familiar with:</p>



<p>The schema is just like writing a&nbsp;<a href="http://swagger.io/getting-started/" target="_blank" rel="noreferrer noopener">Swagger documentation</a>&nbsp;for your API, except that in GraphQL the schema is always enforced. The schema also completely removes the need for you to specify a router and parse url patterns. Having a strictly enforced schema ensures that documentation is always complete and up to date.</p>



<p>The resolve functions are similar to the code you would write inside your REST endpoints, except that each of them has a clear responsibility for fetching items of just one type. I have yet to see a REST API where code is organized as neatly as it is in GraphQL.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="844" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ-1024x844.png" alt="" class="wp-image-196" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ-1024x844.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ-300x247.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ-768x633.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ-1536x1266.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ-1200x989.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_f_XvFD7FvliMM74WHJ0vRQ.png 1618w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>GraphQL replaces REST “best practices” with a clear &amp; simple structure</figcaption></figure>



<p>Because GraphQL gives you a logical structure in which to fit your code, I found that building GraphQL servers is much faster and easier than building a REST API.</p>



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



<h2 class="wp-block-heading" id="fd74"><a href="#3-can-i-use-graphql-with-angular-react-ember-redux" aria-hidden="true" class="aal_anchor" id="3-can-i-use-graphql-with-angular-react-ember-redux"><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. Can I use GraphQL with &lt;Angular/React/Ember/Redux&gt;?</h2>



<p>For a while, Relay was the only open-source GraphQL client available, but that isn’t true now.</p>



<p>Now, Relay is just one of many GraphQL clients, and you don’t have to use it to try GraphQL. There are other clients available, such as&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;or&nbsp;<a href="https://github.com/kadirahq/lokka" target="_blank" rel="noreferrer noopener">Lokka</a>. You could even use GraphQL without any client and send raw strings to the server, like you do for REST!</p>



<p>Relay is the JavaScript client for GraphQL that Facebook uses. It’s an impressive piece of software that adds many things on top of GraphQL, such as query merging, pagination and deferred queries. Relay is pretty tightly integrated with React and doesn’t support other view layers — at least not at the moment. It solves many difficult problems, which makes it quite complex: Relay can have a pretty steep learning curve.</p>



<p>While Relay is without a doubt the best GraphQL client at Facebook’s level of complexity, many developers we’ve talked to wish there was something simpler they could use. Others have apps in Angular or Ember, or they want Redux to manage all of their app state. In many of these cases, Relay is not the ideal choice.</p>



<p>So what alternatives are there?</p>



<p>If you’re looking for a client that does caching and integrates well with your view layer and state management,&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;is probably your best choice: It’s easy to use and&nbsp;<a href="http://docs.apollostack.com/" target="_blank" rel="noreferrer noopener">well-documented</a>. It has&nbsp;<a href="http://docs.apollostack.com/apollo-client/react.html" target="_blank" rel="noreferrer noopener">integrations for React</a>,&nbsp;<a href="http://docs.apollostack.com/apollo-client/redux.html" target="_blank" rel="noreferrer noopener">Redux</a>&nbsp;and&nbsp;<a href="http://docs.apollostack.com/apollo-client/angular2.html" target="_blank" rel="noreferrer noopener">Angular 2</a>, and other integrations — for example React Native — are actively being worked on.</p>



<p>If you’re looking for a simple tool that just helps you send GraphQL queries and responses, take a look at&nbsp;<a href="https://github.com/kadirahq/lokka" target="_blank" rel="noreferrer noopener">Lokka</a>. It clocks in at barely over 100 lines of code, which shows how simple a GraphQL client can be.</p>



<h2 class="wp-block-heading" id="37a2"><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>If you were curious about GraphQL before, but didn’t know everything you needed to know to try it out, I hope this post fixed that. If there are other questions that are keeping you from trying it out, let me know in the comments!</p>



<p>If this post got you interested in building a GraphQL server, you might find my&nbsp;<a href="https://medium.com/apollo-stack/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener">GraphQL server tutorial</a>&nbsp;useful, which also has a screencast that you can follow along.</p>


How do I GraphQL?


<p>Last week, we had a great conversation with&nbsp;<a href="https://medium.com/u/1a3894eae0ac?source=post_page-----48e8349fd75----------------------" target="_blank" rel="noreferrer noopener">Ben Strahan</a>, Paul Dowman, and&nbsp;<a href="https://medium.com/u/60ad00146009?source=post_page-----48e8349fd75----------------------" target="_blank" rel="noreferrer noopener">Martijn Walraven</a>&nbsp;about the tradeoffs between Cordova, fully native apps, and React Native in the Meteor context, and how Apollo fits into that story as a unified data loading system.</p>



<p>Check it out to hear about how all of the pieces fit together:</p>



<figure class="wp-block-embed-youtube wp-block-embed is-type-video is-provider-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="Transmission - Ep 11: Apollo, GraphQL, React Native, and the future of Meteor" width="580" height="326" src="https://www.youtube.com/embed/J4ma5Qow34M?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div></figure>



<p>Martijn most recently finished rewriting Meteor’s Cordova integration to use native code to securely and incrementally ship new JavaScript code for production mobile apps. Now, he’s setting his sights on enabling Apollo to work well with hybrid native apps built with frameworks like React Native and NativeScript, as well as building fully native shells so that iOS and Android apps can easily integrate GraphQL data.</p>



<p>If you want to hear more from Martijn, catch his upcoming talk:</p>



<p><strong>“Progressive enhancement for mobile apps: exploring the continuum between Cordova and React Native.”</strong></p>



<p>First, on May 19th at&nbsp;<a href="http://pgday.phonegap.com/eu2016/speaker/martijnwalraven" target="_blank" rel="noreferrer noopener">PhoneGap Day EU</a>, then June 3rd at&nbsp;<a href="https://www.react-europe.org/#schedule" target="_blank" rel="noreferrer noopener">React Europe</a>. Good luck on the talks, Martijn!</p>


Apollo, GraphQL, React Native, and Meteor


<p>For a long time now, people have been excited about the potential of APIs and “mashup” apps. At every hackathon, you see tons of companies lining up to give out prizes for using their API to build something cool. There are many services these days that promise to make building, using, and documenting APIs easy and fun, to unlock the value in your organization’s data. There are also many conferences, websites, and blogs about API development.</p>



<p>But even though we’ve spent so much time improving API tools, we haven’t quite fulfilled the ultimate promise: self-documenting, semantic, easily consumable data.</p>



<p>You can’t yet dream up an app and start building it without searching through a ton of documentation, specialized packages and SDKs, and maybe even building an extra API server on top of your APIs because those APIs aren’t really what you needed in the first place.</p>



<p>What if there were a uniform and descriptive API language that all of your tools could understand and integrate seamlessly into your design and development workflow? That is the destiny of GraphQL.</p>



<p>You can think of GraphQL like REST 2.0 — it’s a nested data fetching language that works on top of a strongly-typed self-documenting description of all of the data available in your system. Given that every GraphQL API must fit these parameters, we can take advantage of that information to build some really next-level developer tools. We already talked about&nbsp;<a href="https://medium.com/apollo-stack/mocking-your-server-with-just-one-line-of-code-692feda6e9cd#.bllz5yhid" target="_blank" rel="noreferrer noopener">mocking your backend data with one line of code&nbsp;</a>— what else could we do?</p>



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



<h2 class="wp-block-heading" id="73c5"><a href="#try-it-today-validate-queries-with-eslint" aria-hidden="true" class="aal_anchor" id="try-it-today-validate-queries-with-eslint"><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>Try it today: Validate queries with ESLint</h2>



<p>Think about the API you’re using in your React or Angular app right now. Do you know the answer to any of the following questions?</p>



<ol class="wp-block-list"><li>Which parts of your many frontend apps are using certain endpoints?</li><li>Are there any parts of your frontend code that have typos when accessing different fields on your API responses?</li><li>If you made any changes to your API, are there any of your frontend apps that you forgot to update to the new format?</li></ol>



<p>Perhaps if you have the most principled code review and documentation in the world, then you know. But for most of us, it’s a mystery — if you have tons of places that are accessing your backend data, making any changes to that backend can be a gamble, and it’s not clear when you’re writing your frontend code if you made any typos.</p>



<p>With GraphQL, you can know, because you can check what data your frontend is requesting statically by inspecting the queries in your code.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="595" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA-1024x595.png" alt="" class="wp-image-191" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA-1024x595.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA-300x174.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA-768x446.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA-1536x893.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA-1200x698.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_TO8DN4ntNfQUiiQmsjYIOA.png 1906w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Get alerted immediately if you make a typo in your query. Can your REST API do that?</figcaption></figure>



<p>As an example, I put together an ESLint plugin for GraphQL, which validates your queries against a backend schema. As you type into your editor, it is constantly checking that the data you’re trying to fetch is actually valid — no more typos in endpoint parameters or field names!</p>



<p>If you’re already using GraphQL in your JavaScript app, try it now:<a href="https://github.com/apollostack/eslint-plugin-graphql" target="_blank" rel="noreferrer noopener">apollostack/eslint-plugin-graphqleslint-plugin-graphql — Check your GraphQL query strings against a schema.github.com</a></p>



<p>Having a tool like this effectively reduces the gap between the client and server components of your app, without coupling them. Since every GraphQL API server can easily export a schema — basically a description of all of the types of data that can be fetched from that server — you can write your server in any language you want, but use the same tools on the frontend to validate the queries.</p>



<p>Better yet, GraphQL includes deprecation as a first-class feature, so you can slowly phase out usage of a certain type or field until you are sure no client is using it anymore.</p>



<p>This is just a simple example of the kinds of tools you can build on top of GraphQL. But let’s not stop there, and dream bigger!</p>



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



<h2 class="wp-block-heading" id="8729"><a href="#wish-list-of-graphql-developer-tools" aria-hidden="true" class="aal_anchor" id="wish-list-of-graphql-developer-tools"><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>Wish list of GraphQL developer tools</h2>



<p>There are so many tools that could be built for GraphQL that couldn’t really be built on top of any other system.</p>



<h3 class="wp-block-heading" id="404e"><a href="#in-editor-query-autocompletion" aria-hidden="true" class="aal_anchor" id="in-editor-query-autocompletion"><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>In-editor query autocompletion</h3>



<p>The linter plugin above already tells you when you’ve made a typo in one of your queries, right inside your editor. What if we could actually suggest different fields directly in there?</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="572" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_wLrhY74ZTD6_oD7H0eaeRg-1024x572.gif" alt="" class="wp-image-190" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_wLrhY74ZTD6_oD7H0eaeRg-1024x572.gif 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_wLrhY74ZTD6_oD7H0eaeRg-300x168.gif 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_wLrhY74ZTD6_oD7H0eaeRg-768x429.gif 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>This is GraphiQL, a standalone query IDE. What if you could do this, directly in your editor? (Thanks to&nbsp;<a href="https://medium.com/u/ddde6379e161?source=post_page-----42529706ae78----------------------" target="_blank" rel="noreferrer noopener">Ramsay Lanier</a>&nbsp;for the awesome GIF from his post&nbsp;<a href="https://medium.com/@rmmmsy/wordpress-with-node-react-and-graphql-part-3-the-schema-8569a89016c#.wh1nqb67a" target="_blank" rel="noreferrer noopener">WordPress with Node, React, and GraphQL</a>)</figcaption></figure>



<p>You might never need to look up your API documentation again!</p>



<h3 class="wp-block-heading" id="167a"><a href="#ui-design-with-real-data" aria-hidden="true" class="aal_anchor" id="ui-design-with-real-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>UI design with real data</h3>



<p><a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----42529706ae78----------------------" target="_blank" rel="noreferrer noopener">James Baxley</a>&nbsp;hooked me up with an idea this week that blew my mind. Many designers use tools like Sketch to prepare UI designs and mockups, and Sketch plugins can&nbsp;<a href="https://github.com/preciousforever/sketch-data-populator" target="_blank" rel="noreferrer noopener">merge generated data with the designs</a>. What if you could just load up an arbitrary query, and get either mocked data from your prepared mocks or real data from your production server to test out your design?</p>



<p>You could do a similar thing with&nbsp;<a href="https://medium.com/u/233a53961f2f?source=post_page-----42529706ae78----------------------" target="_blank" rel="noreferrer noopener">Arunoda</a>’s&nbsp;<a href="https://github.com/kadirahq/react-storybook" target="_blank" rel="noreferrer noopener">React Storybook</a>&nbsp;— there could be a plugin that lets you simply write a GraphQL query that matches the shape of the arguments for your components, and gives you the data you need.</p>



<h3 class="wp-block-heading" id="e065"><a href="#some-more-ideas" aria-hidden="true" class="aal_anchor" id="some-more-ideas"><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>Some more ideas</h3>



<p>If you just sit down for a minute and think, I’m sure you can up with a ton more stuff:</p>



<ul class="wp-block-list"><li><strong>Guard against unused data:</strong>&nbsp;When you have a REST API, the backend will often return fields that you don’t use on the frontend. But with GraphQL, you get to specify exactly the fields you need, so shouldn’t your editor warn you when you are fetching a field you don’t actually access?</li><li><strong>Typed result objects:</strong>&nbsp;If you’re programming in a typed language, like Flow, TypeScript, Java, or Swift, your tooling should be able to give you a typed result object from your query. I suspect this is exactly what Facebook is doing internally; after all, GraphQL was initially developed for their mobile apps!</li><li><strong>Build your UI without running your backend:&nbsp;</strong>Since your schema completely defines what types of data you might get out of your API, simple mocking functionality would allow you to work on your app’s UI even before the backend is ready.</li><li><strong>Generate test fixtures as you need them:&nbsp;</strong>Like&nbsp;<a href="https://github.com/apollostack/eslint-plugin-graphql/blob/master/test/schema.graphql" target="_blank" rel="noreferrer noopener">we did for the ESLint plugin tests</a>, you can generate a schema without defining any data loading logic at all, and use that as a fixture for your tests.</li></ul>



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



<h2 class="wp-block-heading" id="a9f6"><a href="#how-do-we-get-it-done" aria-hidden="true" class="aal_anchor" id="how-do-we-get-it-done"><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>How do we get it done?</h2>



<p>With all of the potential of GraphQL, it’s clear that we are in the very early days of this ecosystem. I suspect we’ve barely discovered 5% of what is possible, and as we as a community build more and more of these tools it’ll become clear just how much of a quantum leap GraphQL really is. On the Apollo team, we’re dedicated to pushing the very limits of that potential.</p>



<p>One of the things that’s going to be really valuable for development tools specifically is having a standard way to&nbsp;<a href="http://graphql.org/docs/introspection/" target="_blank" rel="noreferrer noopener">introspect</a>&nbsp;information about one’s GraphQL schema, including types, queries, mutations, and&nbsp;<a href="https://medium.com/apollo-stack/graphql-schema-decorators-3c01a445b628#.4z7nh0agi" target="_blank" rel="noreferrer noopener">metadata</a>.</p>



<p>I’ve started a repository called “graphqlrc” where we can talk about the various needs of such a system, and how it could be implemented. I’ve called it “graphqlrc” to align with a venerable history of config files, but it could be anything — a file, worker service, or something else. If you’re as hyped as I am about the possibilities for GraphQL developer tools, let’s talk there:</p>



<p><a href="https://github.com/apollostack/graphqlrc">https://github.com/apollostack/graphqlrc</a></p>



<p>Also, if you’re interested in GraphQL, APIs, or data loading in general, follow our&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>&nbsp;publication here on Medium!</p>


Power tools for your API


<p>Last week on&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>, we announced our&nbsp;<a href="https://medium.com/apollo-stack/introducing-the-apollo-graphql-data-stack-5d005312cbd0" target="_blank" rel="noreferrer noopener">alpha release</a>, complete with several demo apps and a&nbsp;<a href="https://medium.com/apollo-stack/tutorial-building-a-graphql-server-cddaa023c035" target="_blank" rel="noreferrer noopener">tutorial for building a GraphQL server</a>. This week I want to write about a really exciting feature that I’m working on — schema decorators.</p>



<p>Imagine if all you needed to build a GraphQL server was a schema declaration. No code in resolve functions, no custom logic, just a schema written in GraphQL schema language.</p>



<p>Or imagine that you want to add a functionality — like checking authorization or validating arguments — to different parts of your schema in a simple way.</p>



<p>Schema decorators will allow you to do both of these things and more! They enable you to add features to your schemas with reusable modules, and even make schema definitions portable across programming languages. With schema decorators, you can build reusable modules that do any of the following and more:</p>



<ul class="wp-block-list"><li>Adding annotations/metadata to the schema</li><li>Enforcing auth checks</li><li>Argument validation</li><li>Logging and profiling</li><li>Error handling</li><li>Connecting to backend data stores</li><li>Filtering or sorting of results</li></ul>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="682" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-1024x682.jpg" alt="" class="wp-image-187" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-1024x682.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-300x200.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-768x512.jpg 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-1536x1024.jpg 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-2048x1365.jpg 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-1200x800.jpg 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_V09_pQQqmUbtX0DDgPS10Q-1980x1320.jpg 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Schema decorators are GraphQL’s reusable parts</figcaption></figure>



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



<p>Right now, GraphQL allows you to customize the way the server executes a query by adding directives , but there is no similar functionality for schemas. As a developer, you have only a handful of ways to modify a schema:</p>



<ul class="wp-block-list"><li>You can create custom types and combine them into a schema.</li><li>You can write arbitrary code inside resolve functions.</li><li>You can add descriptions to types, fields and args, and you can deprecate fields.</li></ul>



<p>GraphQL currently lacks a standard and modular way to add features to the schema.</p>



<h2 class="wp-block-heading" id="edf2"><a href="#what-are-schema-decorators" aria-hidden="true" class="aal_anchor" id="what-are-schema-decorators"><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 are schema decorators?</h2>



<p>Schema decorators are similar to function decorators in Python or ES2016 — they alter the behavior of the thing they decorate. While Python decorators only apply to functions, our proposal for schema decorators can be selectively applied to arguments, fields, types or the schema.</p>



<p>Rather than just providing a way to add metadata to a schema, decorators also establish a standard way for defining the semantics of that metadata.</p>



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



<p><strong>Goals for schema decorators:</strong></p>



<ul class="wp-block-list"><li>They must be flexible enough to allow a wide range of behaviors</li><li>They must be well-specified, so it’s clear when and where they can be used</li><li>They must be introspectable, such that the information is preserved after a parse/print cycle.</li><li>They must be fully self-contained, meaning that it is not necessary to modify the execution engine to use them.</li><li>There should be a core set of decorators that have the same meaning and function across implementations of GraphQL in different languages.</li></ul>



<p>Schema decorators share some similarities with GraphQL directives, but they differ in a few key ways:</p>



<ul class="wp-block-list"><li>Directives apply to queries, decorators apply to the schema</li><li>Directives come&nbsp;<em>after</em>&nbsp;the thing they apply to, decorators come&nbsp;<em>before</em>&nbsp;it (as they do in every other programming language)</li><li>Directives (currently) achieve their behavior through changes to the source code of the query execution engine, whereas decorators rely on a set of standard hooks.</li></ul>



<h2 class="wp-block-heading" id="555a"><a href="#how-do-schema-decorators-work" aria-hidden="true" class="aal_anchor" id="how-do-schema-decorators-work"><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>How do schema decorators work?</h2>



<p>The main benefit of schema decorators is that they can be used to add semantically meaningful metadata to a schema specified in GraphQL schema language:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">// Sample GraphQL schema with decorators

+connector(storage: &quot;MySQL&quot;)
+doc(description: &quot;A Person&quot;)
type Person {
  +mock(type: &quot;ID&quot;)
  id: Int
  
  +mock(raw: &quot;John&quot;)
  name: String
  
  +requireAuthRole(role: &quot;admin&quot;)
  age: Int
}

+log(info: &quot;query&quot;)
type Query {
  findPerson(name: String!): Person
  
  +requireAuthRole(role: &quot;admin&quot;)
  allPeople(): [Person]
}

+log(info: &quot;mutation&quot;)
+requireAuthRole(role: &quot;admin&quot;)
type Mutation {
  addPerson(
    +validateLength(min: 1, max:100)
    name: String!
  ): Person
  removePerson(id: Int!): Boolean
}

schema {
  query: Query
}</code></pre>



<p>For these decorators to work, they need to be passed into the schema generator, which builds the schema from the AST. Once the schema is built completely, the decorators are applied to the thing they decorate — an argument, a field, a type, or the whole schema.</p>



<p>Behind the scenes, decorators are implemented as classes that fit the decorator interface: the decorator must be named, specify the locations in which it can be used, the arguments that it accepts, and it has a function that gets called when the decorator is applied.</p>



<p>When a decorator is applied, it modifies the schema to achieve the desired effect. For example, the +doc decorator can be used on types, fields and arguments, and it adds a description to the thing it’s applied to. The +log decorator can be applied to the schema, a type, or a field, and it wraps the resolve functions under its scope to add a call to a logger to it. Which logger instance is used can be configured in the constructor of the LogDecorator class.</p>



<p>Using decorator classes behind the scenes means that the decorators can be used with any GraphQL-JS schema, they don’t depend on the shorthand schema notation.</p>



<p>In essence, decorator classes are just a standard interface which returns a function that is then applied to the schema, so they could easily be implemented for GraphQL implementations in other languages.</p>



<p>In GraphQL-JS, this is roughly what decorators would look like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { applyDecorators } from &#039;graphql-tools&#039;;
import {
  GraphQLSchema,
  GraphQLString,
  GraphQLObjectType,
} from &#039;graphql&#039;;
import { Doc, Log } from &#039;graphql-decorators&#039;;

const Logger = { log: (...args) =&gt; console.log(...args) };

const doc = new Doc();
const log = new Log({ logger: Logger });

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: &#039;Query&#039;,
    decorators: [ log.apply({prefix: &#039;query&#039; }) ],
    fields: {
      aString: {
        type: GraphQLString,
        decorators: [ doc.apply({ description: &#039;Returns hello world&#039; }) ],
        resolve: () =&gt; &#039;Hello World&#039;,
      }
    }
  })
});

// call applyDecorators to apply the decorators to the schema
applyDecorators(schema);</code></pre>



<p>Many decorators, such as validation decorators could be used by client libraries to do client-side checking.</p>



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



<p>For decorators to work in other languages, such as Python or Ruby, all that’s needed is an implementation of the same decorator in that language. Once enough decorators are implemented in different languages, your schema becomes completely portable. Imagine how cool it would be if you could easily switch your server from Node.js to Scala or the other way!</p>



<h2 class="wp-block-heading" id="539a"><a href="#how-can-i-use-schema-decorators" aria-hidden="true" class="aal_anchor" id="how-can-i-use-schema-decorators"><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>How can I use schema decorators?</h2>



<p>Schema decorators are a proposal and not fully implemented yet. You can help to improve the spec and build a working implementation!</p>



<p>We’ve started implementing a first version of decorators in&nbsp;<a href="https://github.com/apollostack/graphql-tools/tree/decorators" target="_blank" rel="noreferrer noopener">graphql-tools</a>. So far there is only a prototype that lets you decorate types and fields in GraphQL-JS. We don’t yet have a parser for the schema language, but we hope that’s coming soon as well. You can either help build it or wait until it’s ready in to try it out.</p>



<p>It will still take some time to figure out in what form decorators (or even just metadata) should be added to the GraphQL spec and reference implementation. The way you can take action right now it is to&nbsp;<a href="https://github.com/apollostack/graphql-decorators/issues" target="_blank" rel="noreferrer noopener">join the discussion</a>, sharing your thoughts on it or implementing some decorators of your own and share them with the rest of the community.</p>



<p>In the next few weeks I hope we can come up with a solid spec for decorators that makes them reusable across different languages and implementations. Personally, I’m planning to work on the schema parser and implement a few common and useful decorators to provide an example. My hope is that other members of the community will help improve the spec and implement more decorators to test / demonstrate the viability of the concept.</p>



<p>Here’s how you can participate right now:</p>



<ul class="wp-block-list"><li><a href="https://github.com/apollostack/graphql-decorators/issues/1" target="_blank" rel="noreferrer noopener">Join the discussion on GitHub</a></li><li><a href="https://github.com/apollostack/graphql-decorators" target="_blank" rel="noreferrer noopener">Contribute to the spec / documentation</a></li><li>Implement your own decorator and make a PR to showcase it!</li></ul>



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



<p><em>Schema decorators were inspired by earlier work and ideas from&nbsp;</em><a href="https://medium.com/u/c4e6f5b6291e?source=post_page-----3c01a445b628----------------------" target="_blank" rel="noreferrer noopener"><em>Ville Immonen</em></a><em>, Mikhail Novikov,&nbsp;</em><a href="https://medium.com/u/d9b1a61823fa?source=post_page-----3c01a445b628----------------------" target="_blank" rel="noreferrer noopener"><em>Lee Byron</em></a><em>,&nbsp;</em><a href="https://medium.com/u/e2ddf2faeb4e?source=post_page-----3c01a445b628----------------------" target="_blank" rel="noreferrer noopener"><em>Igor Canadi</em></a><em>, Clinton Wood and others in the following issues and PRs on GraphQL-JS:&nbsp;</em><a href="https://github.com/graphql/graphql-js/issues/114" target="_blank" rel="noreferrer noopener"><em>#114</em></a><em>,&nbsp;</em><a href="https://github.com/graphql/graphql-js/issues/180" target="_blank" rel="noreferrer noopener"><em>#180</em></a><em>,&nbsp;</em><a href="https://github.com/graphql/graphql-js/issues/264" target="_blank" rel="noreferrer noopener"><em>#264</em></a><em>,&nbsp;</em><a href="https://github.com/graphql/graphql-js/issues/265" target="_blank" rel="noreferrer noopener"><em>#265</em></a><em>&nbsp;and #</em><a href="https://github.com/graphql/graphql-js/issues/334" target="_blank" rel="noreferrer noopener"><em>334</em></a><em>.</em></p>


GraphQL schema decorators


<p>Today, I’m excited to announce a technical preview release of the&nbsp;<a href="https://medium.com/apollo-stack/apollo-8b7215bcab1c#.z33k0hqpt" target="_blank" rel="noreferrer noopener">Apollo data stack</a>. There is still a lot of work to do before Apollo is production ready, but we think the components we have now are a great first step.</p>



<p>Our main goal today is to enable people to get their hands dirty experimenting with the different parts, and to seek out contributors who are excited about such a project. If you check out our&nbsp;<a href="http://docs.apollostack.com/" target="_blank" rel="noreferrer noopener">new documentation</a>&nbsp;and you like the direction, please don’t hesitate to join our&nbsp;<a href="http://slack.apollostack.com/" target="_blank" rel="noreferrer noopener">Slack team</a>&nbsp;or file&nbsp;<a href="https://github.com/apollostack" target="_blank" rel="noreferrer noopener">issues or PRs on GitHub</a>.</p>



<h3 class="wp-block-heading" id="a934"><a href="#whats-apollo" aria-hidden="true" class="aal_anchor" id="whats-apollo"><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 Apollo?</h3>



<p>Apollo is our vision for the data stack of the future. It includes both client and server-side components that live between your UI (React, Angular, Reduxor anything else) and your backend services (MongoDB, SQL, REST, etc), shuttling data between the two. You query your data with GraphQL, and the data stack handles the rest.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="576" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2-1024x576.png" alt="" class="wp-image-176" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2-1024x576.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2-300x169.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2-768x432.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2-1536x864.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2-1200x675.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qfcrwiwerEGyg-30BOuPkQ-2.png 1920w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>An architectural diagram from the Apollo talk.</figcaption></figure>



<p>Check out our earlier&nbsp;<a href="https://medium.com/apollo-stack/apollo-8b7215bcab1c#.63eabc3il" target="_blank" rel="noreferrer noopener">post and talk about Apollo</a>&nbsp;to learn about why we are building it, what it is, and where it’s going.</p>



<p>So, what can you start using and looking at today?</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="64" height="64" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/0_2nk_66xbe36mavAb.png" alt="" class="wp-image-175"/></figure>



<h2 class="wp-block-heading" id="3161"><a href="#the-initial-set-of-tools-and-integrations" aria-hidden="true" class="aal_anchor" id="the-initial-set-of-tools-and-integrations"><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 initial set of tools and integrations</h2>



<p>First and foremost, there is now a set of packages you can install from NPM and start experimenting with. The main components are the client and server:</p>



<ol class="wp-block-list"><li><a href="http://docs.apollostack.com/apollo-client/index.html" target="_blank" rel="noreferrer noopener">Apollo Client</a>, a simple, incrementally adoptable GraphQL client built on Redux.</li><li><a href="http://docs.apollostack.com/apollo-server/index.html" target="_blank" rel="noreferrer noopener">GraphQL Tools</a>, a set of useful utilities for GraphQL-JS that enable you to declaratively specify your schema, easily mock data, and enjoy improved error reporting.</li></ol>



<p>We also have native integrations for a variety of environments:</p>



<ol class="wp-block-list"><li><a href="https://github.com/apollostack/react-apollo" target="_blank" rel="noreferrer noopener">react-apollo</a>, a React integration for the Apollo Client heavily inspired by react-redux.</li><li><a href="https://github.com/apollostack/angular2-apollo" target="_blank" rel="noreferrer noopener">angular2-apollo</a>, an integration for Angular 2.</li><li><a href="http://docs.apollostack.com/apollo-client/meteor.html" target="_blank" rel="noreferrer noopener">Meteor integration</a>, with easy conventions for working with the Meteor accounts system and web server.</li><li><a href="http://docs.apollostack.com/apollo-client/redux.html" target="_blank" rel="noreferrer noopener">Redux integration</a>, which lets you keep your client and server data in the same place, and track them with the spectacular Redux DevTools.</li></ol>



<p>If you don’t see your favorite technology here yet, don’t worry — more integrations are coming, and it’s easy to build your own on top of the core packages.</p>



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



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



<p>We’ve whipped together a few small example apps to show how the different parts might fit together. We’re always looking for improvements and feedback on these apps, and they’ll get better as Apollo progresses. We plan to start integrating Apollo into our own production apps in the very short term, and we’re going to bring those learnings back to the packages and examples.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="794" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ-1024x794.png" alt="" class="wp-image-174" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ-1024x794.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ-300x233.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ-768x596.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ-1536x1191.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ-1200x931.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_hhrEz_FUTUyoZH4Wae5cyQ.png 1550w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>The Discourse example app, linked to try.discourse.org.</figcaption></figure>



<p>Here are the three examples we have today:</p>



<ul class="wp-block-list"><li><a href="https://github.com/apollostack/apollo-demo" target="_blank" rel="noreferrer noopener">A full-stack app with a Material UI React frontend on top of Discourse</a></li><li><a href="https://github.com/apollostack/apollo-server-tutorial" target="_blank" rel="noreferrer noopener">A GraphQL server example that uses SQL, MongoDB + REST</a></li><li><a href="https://github.com/apollostack/meteor-starter-kit" target="_blank" rel="noreferrer noopener">A bare-bones Meteor starter kit</a></li></ul>



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



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



<p>In order to make it as easy as possible to try this stuff out, we’ve put together a&nbsp;<a href="http://docs.apollostack.com/" target="_blank" rel="noreferrer noopener">detailed documentation site</a>&nbsp;for the current set of packages. The APIs will change frequently at this early stage, so check back often to see what we’re cooking!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="683" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-1024x683.png" alt="" class="wp-image-173" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-1024x683.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-300x200.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-768x512.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-1536x1025.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-1200x800.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw-1980x1321.png 1980w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Nj_FdDmt2V-jrtXp1NSCPw.png 2000w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>docs.apollostack.com</figcaption></figure>



<p>And to top it off, we now have&nbsp;<a href="http://www.apollostack.com/" target="_blank" rel="noreferrer noopener">a beautiful new website</a>&nbsp;to introduce people to the project!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="598" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-1024x598.png" alt="" class="wp-image-172" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-1024x598.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-300x175.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-768x448.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-1536x897.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-2048x1195.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-1200x700.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_mG-H0n0wM44a4v20au_9Mg-1980x1156.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>apollostack.com</figcaption></figure>



<p>For the near future, we are focused on building a full-stack solution for GraphQL that’s easy to get started with and scales as your app grows, both in the number of users and complexity of the code.</p>



<p>This whole journey started with a post called&nbsp;<a href="http://info.meteor.com/blog/reactive-graphql" target="_blank" rel="noreferrer noopener">Reactive GraphQL</a>, and we’re always keeping that goal in mind. Even though reactivity is not in the immediate plans, you can achieve it today by refetching data or mixing Meteor subscriptions with your GraphQL queries, and we plan to make this approach much better in the short term.</p>



<p><strong>Join us on Slack:&nbsp;</strong>If the projects we are working on right now sound like something you need, and you want to get started with it right away or contribute to the project,&nbsp;<a href="http://slack.apollostack.com/" target="_blank" rel="noreferrer noopener">drop us a line on Slack</a>&nbsp;and we’ll set you up.</p>



<p><strong>Follow us on Medium:&nbsp;</strong>We’re going to keep blogging about our progress with Apollo and what we learn along the way&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">right here on Medium</a>. Let’s keep in touch and build the future together!</p>



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



<p><em>Big thanks to all of the contributors who have helped us get this preview together:&nbsp;</em><a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----5d005312cbd0----------------------" target="_blank" rel="noreferrer noopener"><em>James Baxley III</em></a><em>,&nbsp;</em><a href="https://medium.com/u/2a8267bb006f?source=post_page-----5d005312cbd0----------------------" target="_blank" rel="noreferrer noopener"><em>John Pinkerton</em></a><em>,&nbsp;</em><a href="https://medium.com/u/994bfa6cc0a8?source=post_page-----5d005312cbd0----------------------" target="_blank" rel="noreferrer noopener"><em>Maxime Quandalle</em></a><em>,&nbsp;</em><a href="https://medium.com/u/2237c12ffc9c?source=post_page-----5d005312cbd0----------------------" target="_blank" rel="noreferrer noopener"><em>Brady Whitten</em></a><em>,&nbsp;</em><a href="https://medium.com/u/4ef692b3f3a0?source=post_page-----5d005312cbd0----------------------" target="_blank" rel="noreferrer noopener"><em>Louis DeScioli</em></a><em>, and&nbsp;</em><a href="https://github.com/kamilkisiela" target="_blank" rel="noreferrer noopener"><em>Kamil Kisiela</em></a><em>.</em></p>


Introducing the Apollo GraphQL data stack


<p>Last week I wrote&nbsp;<a href="https://medium.com/apollo-stack/mocking-your-server-with-just-one-line-of-code-692feda6e9cd" target="_blank" rel="noreferrer noopener">a post</a>&nbsp;about how&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL</a>&nbsp;makes mocking your server API really easy. Some people have asked me what I’ve used to build that, because the schema looks quite different from what they are used to seeing with&nbsp;<a href="https://github.com/graphql/graphql-js" target="_blank" rel="noreferrer noopener">GraphQL-JS</a>. The answer is: I used GraphQL-JS!</p>



<p>In case you are new to GraphQL: GraphQL-JS is Facebook’s reference implementation of the GraphQL spec, and a library that you can use to build your own things with GraphQL. Most people are not aware of the second part, and that’s what this post is about.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="682" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w-1024x682.png" alt="" class="wp-image-168" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w-1024x682.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w-300x200.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w-768x511.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w-1536x1023.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w-1200x799.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qUEj7Oqec0UOyQRKU3uC2w.png 1802w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>GraphQL-JS is more than a reference implementation of GraphQL, it’s a well-organized library of tools.</figcaption></figure>



<h3 class="wp-block-heading" id="99c6"><a href="#what-is-graphql-js" aria-hidden="true" class="aal_anchor" id="what-is-graphql-js"><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 GraphQL-JS?</h3>



<p>GraphQL-JS is the reference implementation of the GraphQL spec, but it’s also a library of useful tools for building servers, clients and tooling for GraphQL.</p>



<p>If the library aspect of GraphQL-JS is news to you, that might be because it’s not documented at all! I’ve you’ve been using GraphQL at all, chances are that you used the only function that’s documented: graphql(schema, query).</p>



<p>If you look under the hood, though, you will notice that GraphQL-JS exports a lot more than that one function, and some of the things it exports are really useful for building your own GraphQL servers, clients and tooling.</p>



<p>This post is going to be a quick tour of a few of the most useful functions that GraphQL-JS exports.</p>



<p>Because there’s not much documentation, for each function I’ll include a code snippet for how to import it, and a link to the source code, which you can inspect to see how to use that function.</p>



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



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



<pre class="wp-block-preformatted">import { parse } from 'graphql';</pre>



<p><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/language/parser.js#L137" target="_blank" rel="noreferrer noopener">Source code for parse.</a></p>



<p>You’re probably not surprised that GraphQL-JS exports a parser that you can use to parse queries. But did you know that it can also parse the schema notation? That feature was added recently in version 0.5.0, and it is incredibly useful. It means that with a little tooling you can now write this:</p>



<pre class="wp-block-preformatted">type Book {<br>  id: ID!<br>  title: String<br>  authors: [Author]<br>}</pre>



<p>instead of this:</p>



<pre class="wp-block-preformatted">const Book = new GraphQLObjectType({<br>  name: 'Book',<br>  fields: () =&gt; ({<br>    id: { type: new GraphQLNonNull(GraphQLID) },<br>    title: { type: GraphQLString },<br>    author: { type: new GraphQLList(Author) },<br>  })<br>}</pre>



<p>The first one is a lot more readable, right?</p>



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



<h2 class="wp-block-heading" id="487b"><a href="#introspectionquery-and-buildclientschema" aria-hidden="true" class="aal_anchor" id="introspectionquery-and-buildclientschema"><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>introspectionQuery and buildClientSchema</strong></h2>



<pre class="wp-block-preformatted">import { <br>  introspectionQuery,<br>  buildClientSchema, <br>} from 'graphql';</pre>



<ul class="wp-block-list"><li><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/utilities/introspectionQuery.js#L14" target="_blank" rel="noreferrer noopener">Source code for introspectionQuery</a></li><li><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/utilities/buildClientSchema.js#L76" target="_blank" rel="noreferrer noopener">Source code for buildClientSchema</a></li></ul>



<p>Did you ever wonder what query GraphiQL sends to the server to learn about its schema? It’s quite a long and intricate query, but lucky for us, it’s also exported by GraphQL-JS. BuildClientSchema can take the output of the introspection query and build a schema out of it, which you can then use to do various things, such as validate queries before sending them to the server. Keep in mind that it’s not exactly the same as the schema on the server, because the introspection query doesn’t tell you about resolve functions and other things that are needed for executing a query.</p>



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



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



<pre class="wp-block-preformatted">import { printSchema } from 'graphql';</pre>



<p><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/utilities/schemaPrinter.js#L27" target="_blank" rel="noreferrer noopener">Source code for printSchema.</a></p>



<p>Do you ever get confused by all the curly braces and parentheses in your server schema? I certainly do. If you do, too, you might want to consider using&nbsp;<em>printSchema</em>&nbsp;to print your schema in the shorter form.</p>



<p>If you use its sibling&nbsp;<em>printIntrospectionSchema</em>&nbsp;together with&nbsp;<em>introspectionQuery</em>, you could even print the schema of any GraphQL server that you are curious about. For example, you could point it at&nbsp;<a href="https://www.graphqlhub.com/" target="_blank" rel="noreferrer noopener">GraphQL-hub</a>&nbsp;to find out what its Twitter, GitHub or any of the other schemas look like. If you don’t already know GraphQL-hub, you should go check it out, it’s an open-source project that lets you query popular APIs (Twitter, GitHub etc.) with GraphQL!</p>



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



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



<pre class="wp-block-preformatted">import { validate } from 'graphql';<br>import { execute } from 'graphql';</pre>



<ul class="wp-block-list"><li><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/validation/validate.js#L36" target="_blank" rel="noreferrer noopener">Source code for validate.</a></li><li><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/execution/execute.js#L103" target="_blank" rel="noreferrer noopener">Source code for execute.</a></li></ul>



<p>The main graphql function from the documentation is really convenient. Given a schema and a query it validates the query and then executes it. That’s great, but sometimes you might only want to validate or execute the query — not both — and that’s precisely what validate and execute are for.</p>



<p>Validate, for example, can be used to validate a query on the client before sending it to the server, which can save some time if the query is invalid, and it can be easier to extract error messages from, because the errors don’t have to be serialized.</p>



<p>Execute on the other hand could be used without first calling validate when you’ve pre-validated all of your queries. Apparently this is what Facebook does: their GraphQL queries are sent to the server and validated at build-time. If the query is valid, the server stores it and returns a unique identifier for it. At runtime, instead of sending the whole query, the clients just send that unique identifier, which is much more compact. Because the server already knows that the query is valid, the validation step can be skipped.</p>



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



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



<pre class="wp-block-preformatted">import { buildASTSchema } from 'graphql';</pre>



<p><a href="https://github.com/graphql/graphql-js/blob/dd0297302800347a20a192624ba6373ee86836a3/src/utilities/buildASTSchema.js#L113" target="_blank" rel="noreferrer noopener">Source code for buildASTSchema.</a></p>



<p>A bit earlier I wrote that with the new parser and a little bit of tooling you can build your entire schema from a shorter notation. BuildASTSchema is the other crucial part there. Parse produces an AST, and buildASTSchema turns that AST into a GraphQLSchema.</p>



<p>The only thing that’s still missing for it to be an executable schema is information about resolve functions — and depending on your schema also resolveType for interfaces, and a few other things.</p>



<p>I’ve written a little tool kit called&nbsp;<a href="https://github.com/apollostack/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools</a>&nbsp;which does exactly that (and a few more things). You can use it to add resolve functions to a schema that was created with buildASTSchema. If you’re interested, you can check it out on&nbsp;<a href="https://github.com/apollostack/graphql-tools" target="_blank" rel="noreferrer noopener">GitHub</a>&nbsp;and install it from npm.</p>



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



<h2 class="wp-block-heading" id="8279"><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>GraphQL-JS is not just a reference implementation, but also a library of incredibly useful tools. It has a lot more to offer than the current documentation on GitHub shows.</p>



<p>I’ve only scratched the surface here — there is a lot more in GraphQL-JS — but I hope it gave you a glimpse of the myriad possibilities. I can’t wait to see all the great things that people are going to build with it!</p>



<p>If this post has piqued your interest, you should definitely check out the excellent “<a href="https://www.youtube.com/watch?v=IqtYr6RX32Q" target="_blank" rel="noreferrer noopener">GraphQL source-code overview</a>” by&nbsp;<a href="https://medium.com/u/d9b1a61823fa?source=post_page-----effaca7a81b3----------------------" target="_blank" rel="noreferrer noopener">Lee Byron</a>&nbsp;on Youtube, and take a look at the&nbsp;<a href="https://github.com/graphql/graphql-js/tree/master/src" target="_blank" rel="noreferrer noopener">source code</a>&nbsp;yourself!</p>



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



<p><em>This post is part of the publication&nbsp;</em><a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener"><em>Building Apollo</em></a><em>, where&nbsp;</em><a href="https://medium.com/u/803918030a60?source=post_page-----effaca7a81b3----------------------" target="_blank" rel="noreferrer noopener"><em>Sashko Stubailo</em></a><em>&nbsp;and I regularly write about GraphQL and the new data stack we’re working on, called Apollo.</em></p>


GraphQL-JS: The hidden features


<p><em>(Editor’s note — the concepts in this post are accurate, but some the code samples don’t demonstrate new usage patterns. After reading, consult the&nbsp;</em><a href="http://dev.apollodata.com/tools/graphql-tools/mocking.html" target="_blank" rel="noreferrer noopener"><em>graphql-tools docs</em></a><em>&nbsp;to see how to use mocking today.)</em></p>



<p>Do you think mocking your backend is always a tedious task? If you do, reading this article will probably change your mind…</p>



<p>Mocking is the practice of creating a fake version of a component, so that you can develop and test other parts of your application independently. Mocking your backend is a great way to quickly build a prototype of your frontend and lets you test your frontend without starting up any servers. API mocking is so useful that&nbsp;<a href="https://www.google.com/?ion=1&amp;espv=2#q=mock+rest+api" target="_blank" rel="noreferrer noopener">a quick Google search</a>&nbsp;will turn up dozens of expensive products and services that promise to help you.</p>



<p>Sadly, I think none of the solutions out there makes it as easy as it should be. As it turns out, that’s because they’ve been trying to do it with the wrong technology!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="950" height="724" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_2YJYBlt6h-eSkFdpgBZJTw.jpg" alt="" class="wp-image-164" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_2YJYBlt6h-eSkFdpgBZJTw.jpg 950w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_2YJYBlt6h-eSkFdpgBZJTw-300x229.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_2YJYBlt6h-eSkFdpgBZJTw-768x585.jpg 768w" sizes="auto, (max-width: 950px) 100vw, 950px" /><figcaption>Mocking your backend doesn’t have to be rocket science!</figcaption></figure>



<p>Last week on&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>&nbsp;I wrote about the set of tools that will eventually make up&nbsp;<a href="https://medium.com/apollo-stack/the-apollo-server-bc68762e93b" target="_blank" rel="noreferrer noopener">Apollo Server</a>. Mocking is the first thing we can demo, and I hope you’ll enjoy it!</p>



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



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



<p>Mocking the data a backend would return is very useful for two main reasons:</p>



<ol class="wp-block-list"><li>It lets you start developing a frontend feature when you don’t have a working backend for it yet. This is critical for projects where the frontend and backend components are often developed in parallel.</li><li>It lets you run tests locally without connecting to a real backend, which is much faster and safer. As your codebase grows and your app becomes more complex, starting up all of the server infrastructure just to run some tests isn’t feasible.</li></ol>



<p>If mocking your backend API has such clear benefits, why doesn’t everyone do it? I think it often seems like too much trouble to be worth it.</p>



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



<p>Let’s say your backend is some REST API that is called over http from the browser. You have someone working on the backend, and someone else working on the frontend.&nbsp;The backend code actually determines the shape of the data returned for each REST endpoint, but mocking has to be done in the frontend code.&nbsp;That means the mocking code will break every time the backend changes, unless both are changed at the same time. What’s worse, if you’re doing your frontend testing against a mock backend that is not up to date with your backend, your tests may pass, but your code won’t work. Rather than having to keep more dependencies up to date, the easy option is to just not mock the REST API, or have the backend be in charge of mocking itself, just so it’s all in one place. That may be easier, but it will also slow you down.</p>



<p>The other reason I often hear for why people don’t mock the backend in their project is because it takes time to set up: first you have to include extra logic in your data fetching layer that lets you turn mocking on and off, and second you have to actually describe what that mock data should like. For any non-trivial API that requires a lot of tedious work.</p>



<p>Both of these reasons for why mocking backends is hard are actually due to the same underlying reason: there is no standard REST API description in machine-consumable format and contains all the information necessary for mocking and can be used by both the backend and the frontend. There are some API description standards, like Swagger, but they don’t contain all of the information you need, are cumbersome to write and maintain. Unless you want to pay a lot of money for a service or a product — and maybe even then — mocking is a lot of work.</p>



<p>Actually, I should say mocking&nbsp;<em>was</em>&nbsp;a lot of work, because something is about to change the way with think of APIs. That something is called GraphQL.</p>



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



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



<p>GraphQL makes mocking easy, because it makes you define a type system for your backend. That type system can be shared between your backend and your frontend, and it contains all the information necessary to make mocking incredibly fast and convenient. You literally have no more excuse not to use mocking in development or testing.</p>



<p>If you don’t know about GraphQL yet, I recommend that you first read&nbsp;<a href="https://medium.com/apollo-stack/the-basics-of-graphql-in-5-links-9e1dc4cac055" target="_blank" rel="noreferrer noopener">an Intro to GraphQL</a>, otherwise the rest of this post might seem a bit like magic.</p>



<p>Here’s how easy it is to start mocking your backend for <strong>any</strong> valid GraphQL query with one of the GraphQL-tools we’ve built for Apollo:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// &gt; npm install graphql-tools
import { mockServer } from &#039;graphql-tools&#039;;
import schema from &#039;./mySchema.graphql&#039;;

const myMockServer = mockServer(schema);
myMockServer.query(`{
  allUsers: {
    id
    name
  }
}`);

// returns
// {
//   data: {
//     allUsers:[
//       { id: &#039;ee5ae76d-9b91-4270-a007-fad2054e2e75&#039;, name: &#039;lorem ipsum&#039; },
//       { id: &#039;ca5c182b-99a8-4391-b4b4-4a20bd7cb13a&#039;, name: &#039;quis ut&#039; }
//     ]
//   }
// }</code></pre>



<p>Every GraphQL server needs a schema, so it’s not extra code you need to write just for mocking. And the query is the one your component uses for fetching data, so that’s also not code you write just for mocking. Not counting the import statement, it only took us one line of code to mock the entire backend!</p>



<p>Put that in contrast to most REST APIs out there, where mocking means parsing a URL and returning data in a custom shape for each endpoint. It takes dozens of lines to mock a single endpoint that returns some realistic-looking data. With GraphQL, the shape is encoded in the query, and together with the schema we have enough information to mock the server with a single line of code.</p>



<p>Did I mention that this one line is all you need to return mock data for any valid GraphQL query you could send? Not just&nbsp;<strong>some</strong>&nbsp;valid query,&nbsp;<strong>any</strong>&nbsp;valid query! Pretty cool, right?</p>



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



<h2 class="wp-block-heading" id="6842"><a href="#customizing-mock-data" aria-hidden="true" class="aal_anchor" id="customizing-mock-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>Customizing mock data</h2>



<p>In the example above, the mock server will return completely random IDs and strings every time you query it. When you’ve just started building your app and only want to see if your UI code actually displays something, that’s probably good enough, but as you start to fine-tune your layout, or want to use the mock server to test your component’s logic, you’ll probably need more realistic data.</p>



<p>Luckily, it barely takes any more effort, because customization of mock data is really where the Apollo mocking tool shines. You can customize virtually everything about the mock data that it returns. It lets you do all of the following and more:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// customize mocking per type (i.e. Integer, Float, String)
mockServer(schema, {
  Int: () =&gt; 6,
  Float: () =&gt; 22.1,
  String: () =&gt; &#039;Hello&#039;,
});

// customize mocking per field in the schema (i.e. for Person.name and Person.age)
mockServer(schema, {
  Person: () =&gt; ({
    name: casual.name,
    age: () =&gt; casual.integer(0,120),
  })
});

// mock lists of specific or random length( and lists of lists of lists …)
mockServer(schema, {
  Person: () =&gt; {
    // a list of length between 2 and 6
    friends: () =&gt; new MockList([2,6]),
    // a list of three lists of two items: [[1, 1], [2, 2], [3, 3]]
    listOfLists: () =&gt; new MockList(3, () =&gt; new MockList(2)),
  },
});

// customize mocking of a field or type based on the query arguments
mockServer(schema, {
  Person: () =&gt; {
    // the number of friends in the list now depends on numPages
    paginatedFriends: (o, { numPages }) =&gt; new MockList(numPages * PAGE_SIZE),
  },
});

// You can also disable mocking for specific fields, pass through to the backend, etc.</code></pre>



<p>For each type and each field you can provide a function that will be called on to generate mock data. Mock functions on fields have precedence over mock functions on types, but they work together really nicely: The field mock functions only need to describe the properties of the objects that matter to them, type mock functions will fill in the rest.</p>



<p>The mock functions are actually just GraphQL resolve functions in disguise. What that means is that your mocking can do anything that you could do inside a GraphQL resolve function. If you wanted, you could write your entire backend with it. I’m not saying you should, but you could.</p>



<p>I think the real power of this tool is that while it allows almost arbitrarily complex customization, you can get started really quickly and increase the sophistication of your mocks in tiny steps whenever you need it. Each step is so simple that it will feel like a breeze.</p>



<p>But enough talking, here’s a complete example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { mockServer, MockList } from &#039;graphql-tools&#039;;
import casual from &#039;casual-browserify&#039;;

// The GraphQL schema. Described in more detail here: 
// https://medium.com/apollo-stack/the-apollo-server-bc68762e93b
const schema = `
  type User {
    id: ID!
    name: String
    lists: [List]
  }
  type List {
    id: ID!
    name: String
    owner: User
    incomplete_count: Int
    tasks(completed: Boolean): [Task]
  }
  type Task {
    id: ID!
    text: String
    completed: Boolean
    list: List
  }
  type RootQuery {
    user(id: ID): User
  }
  schema {
    query: RootQuery
  }
`;

// Mock functions are defined per type and return an
// object with some or all of the fields of that type.
// If a field on the object is a function, that function
// will be used to resolve the field if the query requests it.
const server = mockServer(schema, {
  RootQuery: () =&gt; ({
    user: (o, { id }) =&gt; ({ id }),
  }),
  List: () =&gt; ({
    name: () =&gt; casual.word,
    tasks: () =&gt; new MockList(4, (o, { completed }) =&gt; ({ completed })),
  }),
  Task: () =&gt; ({ text: casual.words(10) }),
  User: () =&gt; ({ name: casual.name }),
});

mockServer.query(`
query tasksForUser{
  user(id: 6) {
    id
    name
    lists {
      name
      completeTasks: tasks(completed: true) {
        completed
        text
      }
      incompleteTasks: tasks(completed: false) {
        completed
        text
      }
      anyTasks: tasks {
        completed
        text
      }
    }
  }
}`);</code></pre>



<h2 class="wp-block-heading" id="d3e2"><a href="#live-demo-try-it-yourself" aria-hidden="true" class="aal_anchor" id="live-demo-try-it-yourself"><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>Live demo + try it yourself</h2>



<p>To see the example in action and see what output it generates, head over to the&nbsp;<a href="http://apollostack.github.io/mock-demo/" target="_blank" rel="noreferrer noopener">live demo</a>&nbsp;and click the “play” button a couple of times!</p>



<p>If you want to fiddle around with the example, you can do that — it’s all on GitHub:&nbsp;<a href="https://github.com/apollostack/mock-demo" target="_blank" rel="noreferrer noopener">apollostack/mock-demo</a>. If you’re curious about how it works or want to see what other tools we’re building for GraphQL, then head over to&nbsp;<a href="https://github.com/apollostack/graphql-tools" target="_blank" rel="noreferrer noopener">apollostack/graphql-tools</a>.</p>



<p>Pretty cool, right? All of that becomes possible by using a type system. And that’s only just the beginning — we‘re working on bridging the gap between mocking and the real thing so that your mock server can gradually turn into your real server as you add more functionality to it.</p>



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



<p>If you’ve liked this post, you might also be interested in the other posts on&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>, written by&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----692feda6e9cd----------------------" target="_blank" rel="noreferrer noopener">Sashko</a>&nbsp;and myself. We’re publishing two posts every week, about the stuff we’re working on or thinking about.</p>


Mocking your server with just one line of code

Apollo, the data stack for modern apps


<p>Last week on&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>,&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----bc68762e93b----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;wrote about the&nbsp;<a href="https://medium.com/apollo-stack/building-a-graphql-store-from-first-principles-413e19ea65b4" target="_blank" rel="noreferrer noopener">client-side cache</a>&nbsp;we’re building for GraphQL; this week I want to give you a short overview of what we’re going to do on the server side.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>If you don’t know what GraphQL is, you might want to check out “<a href="https://medium.com/apollo-stack/the-basics-of-graphql-in-5-links-9e1dc4cac055" target="_blank" rel="noreferrer noopener">Intro to GraphQL</a>”.</p></blockquote>



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



<p>The GraphQL reference implementation,&nbsp;<a href="https://github.com/graphql/graphql-js" target="_blank" rel="noreferrer noopener">graphql-js</a>, is great: It contains pretty much everything you need to build your own GraphQL server in JavaScript. Unfortunately, just having all the parts doesn’t mean that building your own server is easy. GraphQL introduces so many new concepts that it’s easy to get lost and not know where to start. That’s where Apollo Server comes in.</p>



<p>Our goals for the project are simple:</p>



<ul class="wp-block-list"><li>Make building a GraphQL server simple and straightforward</li><li>Provide great documentation and guidance for building GraphQL servers</li><li>Provide great tooling: error messages, logging, profiling and more</li></ul>



<h2 class="wp-block-heading" id="7467"><a href="#how-hard-can-it-really-be" aria-hidden="true" class="aal_anchor" id="how-hard-can-it-really-be"><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>How hard can it really be?</h2>



<p>If you’ve never tried to build a GraphQL server yourself, you’re probably wondering: how hard could it really be? Let me give you an example for how you would define a schema with one type in graphql-js:</p>



<figure><iframe loading="lazy" src="https://blog.apollographql.com/media/3952636e6fca4f9cc60e5b39378d8aad" allowfullscreen="" height="901" width="680"></iframe><figcaption>A schema definition for graphql-js</figcaption></figure>



<p>That’s quite a bit of code for a simple schema!</p>



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



<p>Whenever possible, code should be structured in such a way that it is as close as possible to our mental model of it. Every time we have to translate between our code and our mental model, it takes effort. We all know that the way the code looks in our source reflects the way we think about it. If the code is messy and hard to read, it’s much more likely that we’ll be unsure about what exactly it’s doing. That makes the code much harder to debug, and it makes mistakes much more likely. The primary goal of Apollo server should therefore be to make the structure of the code as clear as possible.</p>



<p>The graphql-js schema makes the whole schema appear as an inseparable blob. When you’re new to GraphQL and see this example, it will at best lead you to structure your code badly, and at worst it will turn you away from GraphQL. I think that’s completely unnecessary, because GraphQL itself actually has a very nice underlying structure. All we need to do is have that structure reflected in our code.</p>



<h2 class="wp-block-heading" id="5e98"><a href="#the-structure-of-a-graphql-server" aria-hidden="true" class="aal_anchor" id="the-structure-of-a-graphql-server"><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 structure of a GraphQL server</h2>



<p>After trying out different ways to structure our code, we realized that a GraphQL server basically consists of three parts:</p>



<ol class="wp-block-list"><li>A type system</li><li>A set of stateless resolve functions</li><li>A set of loaders</li></ol>



<p>We’ll go through each of them one by one.</p>



<p><strong>The type system</strong></p>



<p>The first part of a GraphQL server is its type system. The type system defines which types exist, how they relate to each other and how they can be queried through the schema. For the example above, this is our type system definition:</p>



<figure><iframe loading="lazy" src="https://blog.apollographql.com/media/92543c997a7d0780f7d60f7dd82a1502" allowfullscreen="" height="241" width="680"></iframe><figcaption>A schema in GraphQL notation. “!” indicates a required argument</figcaption></figure>



<p>It’s very straight forward to see from the above type definition that a query for a Person takes exactly one (required) argument of type ID.</p>



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



<p><strong>The resolve functions</strong></p>



<p>If you’ve read the examples above carefully, you will have noticed that there is one piece of information missing that was in the schema above: the&nbsp;<em>resolve</em>&nbsp;field of&nbsp;<em>Query.person.</em></p>



<p>Resolve functions tell the GraphQL server how to respond to a request for a certain field of that type. In the example above, there is only one resolve function,&nbsp;<em>Query.person.&nbsp;</em>That function tells the server that it should make a request to the backend and then parse it as JSON. The server will wait until that promise is fulfilled, and then pass the resulting object&nbsp;<em>obj&nbsp;</em>on to the Person type for handling. The Person type doesn’t define any resolve functions, so it expect&nbsp;<em>obj&nbsp;</em>to have the three properties&nbsp;<em>id, name&nbsp;</em>and<em>&nbsp;age.</em></p>



<p>So if we define just the resolve function, it would look like this:</p>



<figure><iframe loading="lazy" src="https://blog.apollographql.com/media/712b73d3b8dd62aea4efe6ea040c0b38" allowfullscreen="" height="219" width="680"></iframe><figcaption>The resolve function for the schema above</figcaption></figure>



<p>With this and the type system above, our server has all the information it needs to respond to the following query:</p>



<pre class="wp-block-preformatted">query {<br>  person(id: 5)<br>}</pre>



<p>So far so good, but that’s only two parts! What about the loaders I was talking about earlier?</p>



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



<p><strong>The loaders</strong></p>



<p>The example above will work, but it’s missing a critical distinction: the way the data is loaded should be separated from the resolve functions. There are a couple of reasons for that:</p>



<ul class="wp-block-list"><li>When your backend changes, you’ll only have to change one loader, not many resolve functions</li><li>One GraphQL query may include the same backend data in more than one place. Having one loader allows you to avoid duplicate code.</li><li>One GraphQL query might make many requests to the same backend, some of which overlap. Using a loader allows you to batch and merge requests where possible.</li><li>Separating the resolve functions and the data loading makes both components much easier to test.</li></ul>



<p>So here’s what the above example should look like:</p>



<figure><iframe loading="lazy" src="https://blog.apollographql.com/media/7a8a5c41cd2d44891bba372304dba0c9" allowfullscreen="" height="395" width="680"></iframe><figcaption>Separating resolve functions from loaders helps with clarity and maintainability</figcaption></figure>



<p>This doesn’t do any batching or caching yet, but with this separation it’s easy to integrate something like&nbsp;<a href="https://github.com/facebook/dataloader" target="_blank" rel="noreferrer noopener">Dataloader</a>.</p>



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



<p>Amazingly enough, graphql-js contains all the parts needed to generate a complete schema from the parts above with only about 10 lines of code! You can check out our&nbsp;<a href="https://github.com/apollostack/apollo-server/tree/vanilla-parser" target="_blank" rel="noreferrer noopener">github repo</a>, if you don’t believe it.</p>



<p>It’s noting that we are not the first ones to come up with this idea,&nbsp;<a href="https://github.com/matthewmueller/graph.ql" target="_blank" rel="noreferrer noopener">graph.ql</a>&nbsp;does pretty much the same thing, and it was in turn inspired by&nbsp;<a href="https://github.com/ForbesLindesay/graphql-schema-gen" target="_blank" rel="noreferrer noopener">graphql-schema-gen</a>.</p>



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



<p>Providing a nice way to structure your GraphQL server is just the first step. For a great developer experience, here are some more things which we’re working on.</p>



<p><strong>Guides and documentation</strong>:</p>



<ul class="wp-block-list"><li>Write a simple but complete guide that developers can follow to build a GraphQL server, similar to the&nbsp;<a href="http://guide.meteor.com/" target="_blank" rel="noreferrer noopener">Meteor guide</a>. The guide will include information on setting up, debugging, authentication, etc.</li></ul>



<p><strong>Error handling, logging, profiling</strong>:</p>



<ul class="wp-block-list"><li>Make it easy to find bugs in resolve functions and data loaders by providing useful error messages for common and uncommon mistakes.</li><li>Make logging information about errors and profiling information easy.</li></ul>



<p><strong>Performance monitoring</strong>:</p>



<ul class="wp-block-list"><li>Integrate logging and performance monitoring to answer the following questions:</li></ul>



<ol class="wp-block-list"><li>Why is my query taking so long? Which backend causes the delay?</li><li>Which parts of query X are hitting the cache vs. a backend?</li><li>What queries are putting the most load on my server?</li></ol>



<p><strong>And more…</strong></p>



<ul class="wp-block-list"><li>A library of loaders for various backends. You can customize these for your app.</li><li>Easy caching across requests to avoid unnecessary load on the backend.</li></ul>



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



<p>That’s a lot of features, so I may have forgotten a few. If you can think of something else that should be part of a good GraphQL server library, let me know! Some of these could — and arguably should — be in graphql-js, but they are not right now. Putting them into Apollo Server first, will give us a chance to introduce, test and refine new features. Once the features have proven themselves, we can submit a pull request upstream.</p>



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



<p>I’m really excited to be working on this project, but I can’t do it all alone. If you are excited about it too, please don’t hesitate — get involved! Comment here, check out&nbsp;<a href="https://github.com/apollostack/apollo-server" target="_blank" rel="noreferrer noopener">the repo</a>, file an issue or submit a pull request. There are so many possibilities!</p>



<p>So… see you on github!?</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><em>Read what we’re learning about GraphQL, data loading, and JavaScript as we work on a new data stack in our new Medium publication,&nbsp;</em><a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener"><em>Building Apollo</em></a><em>.</em></p></blockquote>


The Apollo server


<p>If you’ve been reading other stories in our publication “<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>”, you’ve already heard about&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL</a>. What you may not have heard of is&nbsp;<a href="http://netflix.github.io/falcor/" target="_blank" rel="noreferrer noopener">Falcor</a>. Falcor — a library for data fetching developed by Netflix — is often compared to GraphQL, because they both try to tackle the same problems, but in different ways. In this post, I want to explore the similarities and differences between GraphQL and Falcor.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="466" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw-1024x466.png" alt="" class="wp-image-135" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw-1024x466.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw-300x137.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw-768x350.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw-1536x699.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw-1200x546.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_pHfLn22IXeG7bqmEa8dOcw.png 1560w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>By the end of this post, you’ll know:</p>



<ul class="wp-block-list"><li>What GraphQL and Falcor are</li><li>What problem they are both trying to solve</li><li>What their similarities and differences are</li><li>Why you could implement left-pad (and other functions) only in one, but not the other (see the&nbsp;<a href="http://apollostack.github.io/graphql-left-pad/" target="_blank" rel="noreferrer noopener">example</a>).</li></ul>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>If you don’t want to read the whole article, scroll down to “<em>Quick Summary</em>” for the tl;dr.</p></blockquote>



<p>I’m more familiar with GraphQL than Falcor, but I find them both to be really amazing, and I’ll do my best to cover them equally well.</p>



<p>Ready to find out more? Let’s get started!</p>



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



<h2 class="wp-block-heading" id="1662"><a href="#the-problem-they-solve" aria-hidden="true" class="aal_anchor" id="the-problem-they-solve"><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 problem they solve</h2>



<p>On a high level, both Falcor and GraphQL were designed to solve the same problem — managing the increasingly complex data requirements of modern web/mobile apps.</p>



<p>The best practice for web development has changed significantly over the last few years. While just a few years ago most websites used to be rendered on the server and have only relatively little client-side logic, the opposite is true of new apps today. Single-page applications and clients that implement complex logic are the new reality.</p>



<p>In a Ruby app, your model, your view, and your controller all live on the server. Getting data from your models to your view is not an issue, because almost all the data is right there on the server, where the page is rendered. In modern javascript apps, that is no longer the case: Your controllers and your views now live mostly on the client, but most of the data is still on the server.</p>



<p>With all but the most custom RESTful APIs, fetching data from the server is both costly and complicated: the latency is high, and chances are you will either fetch more data than you need or make more roundtrips you would like — or both! That’s where GraphQL and Falcor come to the rescue.</p>



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



<h2 class="wp-block-heading" id="f202"><a href="#falcor-in-a-nutshell" aria-hidden="true" class="aal_anchor" id="falcor-in-a-nutshell"><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>Falcor in a nutshell</h2>



<p>Falcor has a very simple premise: All of your data is represented as one giant JSON model, and you code the same way whether your data is on the client, or on the server (Falcor will figure it out for you).</p>



<p>To get around the most basic limitations of JSON, Falcor extends it to include references, which just means that JSON can now also represent circular data structures, like graphs. You can query it like so:</p>



<pre class="wp-block-preformatted">// ask for name and age of user with id = 5<br>model.get("users[5]['name','age']");// which will eventually return something like<br>{<br>  "users": {<br>    "5": {<br>      "name": "John Doe",<br>      "age": 33<br>    }<br>  }<br>}// you can also ask for ranges<br>model.get("users[5..7].name);// which eventually returns the following<br>{<br>  "users": {<br>    "5": { "name": "John Doe" },<br>    "6": { "name": "Jane Doe" },<br>    "7": { "name": "Mary Poppins" }<br>  }<br>}</pre>



<p>Falcor then takes care of merging together the requests for all the data your templates need into a single query, and makes sure to only fetch each item once, even if it’s used in multiple places. It also caches it for you in the client, in case you need it again later.</p>



<p>At this point, you’re probably wondering whether all your data has to be stored in JSON, right? That’s where the other part of Falcor comes in: routes. On a Falcor server, you define routes, which match certain paths that can be requested. For example, you could define a route which matches the “users” model from the previous example. How that route gets its data is entirely up to you — it might come from a SQL database, a microservice, or even an external API.</p>



<p>Next, let’s take a look at GraphQL.</p>



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



<h2 class="wp-block-heading" id="7b91"><a href="#graphql-in-a-nutshell" aria-hidden="true" class="aal_anchor" id="graphql-in-a-nutshell"><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>GraphQL in a nutshell</h2>



<p>Unlike the name suggests, GraphQL is not a query language for graph databases. It’s a declarative, strongly typed application-level query language. GraphQL fits between your backend and your frontend. It lets you define a model for your data, and a mapping between that model and your backends.</p>



<p>Here’s how you would write the example queries from above in GraphQL:</p>



<pre class="wp-block-preformatted">graphql.query(`<br>{<br>  user(id: 5){<br>    name<br>    age<br>  }<br>}<br>`);// returns the following<br>{<br>  "user": {<br>    "name": "John Doe",<br>    "age": 33<br>  }<br>}// query for a range<br>{<br>  users(first: 3, after: 4){<br>    id<br>    name<br>  }<br>}// returns the following<br>{<br>  "users": [<br>    { "id": 5, "name": "John Doe" },<br>    { "id": 6, "name": "Jane Doe" },<br>    { "id": 7, "name": "Mary Poppins" }<br>  ]<br>}</pre>



<p>As you can see, the shape of the query closely matches the shape of the data.</p>



<p>GraphQL only defines the query language, and not the actual implementation. It also doesn’t encompass client side tools for query merging, caching and all that fancy stuff. Those are handled by a client-side GraphQL library like Relay. More on that later…</p>



<p>If you want to know more about GraphQL, here’s a&nbsp;<a href="https://medium.com/apollo-stack/the-basics-of-graphql-in-5-links-9e1dc4cac055" target="_blank" rel="noreferrer noopener">short intro post</a>&nbsp;that I wrote a few weeks ago.</p>



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



<p>GraphQL and Falcor have many similarities, these are just a few of them:</p>



<p>As you can see, both GraphQL and Falcor are a layer between your front-end and your backends, neither of them is a replacement for your existing backend.</p>



<p>They have a different syntax, but similar semantics for declaring exactly what data your views need.</p>



<p>Both Falcor and GraphQL (+Relay) fetch your data in one call to the server instead of many, and they cache the data for you.</p>



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



<p>Falcor and GraphQL have a lot of similarities, but they also have some significant differences:</p>



<p>While Falcor is easier to learn and write, GraphQL has a steeper learning curve, but is more powerful.</p>



<p>GraphQL has a schema and static types, Falcor does not have that. There is currently no easy way (that I know of) to tell what type of data your Falcor will return to you.</p>



<p>GraphQL has schema introspection built-in, which allows for some very nice tooling, like Graph<em>i</em>QL. The Falcor docs say that if you know your data, you know your API, but the problem is that often we don’t actually know the data (what was that field called again??), and it would be great if there was some way to explore it. Graph<em>i</em>QL makes that very easy, and it could be integrated directly into your IDE of choice.</p>



<p>GraphQL lets you provide arguments to queries, with Falcor you’re limited to IDs and explicit ranges. That means you can’t implement a search function, a custom sort, or even left-pad (sorry… I couldn’t help it…) on the server.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Check out the&nbsp;<a href="http://apollostack.github.io/graphql-left-pad/" target="_blank" rel="noreferrer noopener">left-pad example in GraphQL</a>, and play around with it!</p></blockquote>



<p>On the other hand, Falcor has built-in&nbsp;<em>set&nbsp;</em>and&nbsp;<em>get&nbsp;</em>operations with straight-forward cache semantics, while GraphQL doesn’t provide that.</p>



<p>GraphQL has an increasingly active ecosystem, with implementations in Java, Python, Ruby, Scala, .NET, Go, etc. As far as I can tell, there are no implementations of Falcor other than the JavaScript one by Netflix. That means if you want to build anything other than a web application with a Node.js server, you’re on your own. [update : there is a .NET router for Falcor on GitHub in “developer preview”, but currently (May 2016) the last commit is from Nov 2015]</p>



<p>By now you can probably see a pattern: Falcor has many features included, is easy to learn, but limited in scope. GraphQL is more powerful, but has a steeper learning curve and requires you to make more choices yourself.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Interesting fact</strong>: You could implement all of Falcor in GraphQL (but not the other way round). In fact, Huey Peterson has already done something similar&nbsp;<a href="http://hueypetersen.com/posts/2015/10/26/querying-graphql-with-falcor/" target="_blank" rel="noreferrer noopener">here</a>.</p></blockquote>



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



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



<p>To summarize, here are the pros and cons that I see at the moment with GraphQL and Falcor:</p>



<p><strong>Falcor Pros:</strong></p>



<ul class="wp-block-list"><li>Really straight forward, easy to learn</li><li>Things like caching and query-merging included</li></ul>



<p><strong>Falcor Cons:</strong></p>



<ul class="wp-block-list"><li>Not as powerful as GraphQL (no arguments)</li><li>No built-in model/schema introspection</li><li>No implementations other than JavaScript, and little visible traction</li></ul>



<p><strong>GraphQL Pros:</strong></p>



<ul class="wp-block-list"><li>Very powerful and flexible</li><li>Static types and introspection — Graph<em>i</em>QL FTW</li><li>Many implementations in other languages, growing community</li></ul>



<p><strong>GraphQL Cons:</strong></p>



<ul class="wp-block-list"><li>Steeper learning curve</li><li>No batteries included. Fair amount of assembling required</li><li>Relay (Javascript GraphQL client) has a steep learning curve</li></ul>



<h2 class="wp-block-heading" id="e602"><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>In my opinion, both GraphQL and Falcor are great solutions, and which one is better depends on the application. If your app doesn’t need anything that Falcor doesn’t already provide, you should probably pick Falcor. If you want to keep the flexibility of using more powerful features either now or later, or want to use it in languages other than JavaScript, GraphQL is most likely the best choice.</p>



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



<p>We could leave it at that, but&nbsp;<strong>wouldn’t it be great if we could bring the simplicity of Falcor to GraphQL, without having to give up any of its power?</strong></p>



<p>That’s exactly what we’re doing with&nbsp;<a href="http://www.apollostack.com/" target="_blank" rel="noreferrer noopener">Apollo</a>: we’re building a data stack based on GraphQL that will be as easy to learn and use as Falcor, but with all the power of GraphQL at your disposal when you need it. Like Meteor, Apollo will be zero-boilerplate, no-nonsense and quick to set up, but with all the flexibility of a library that you can just plug in to work with your existing app!</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>We’re just a few days away from showing you our first demo of&nbsp;<a href="http://www.apollostack.com/" target="_blank" rel="noreferrer noopener">Apollo</a>, so make sure to subscribe if you don’t want to miss it!</p></blockquote>



<p>If you’re curious, you can read more on our Medium publication&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>.</p>


Announcement

Effortless Data Fetching: Introducing Apollo Connectors for REST APIs

More expressive schemas with @oneOf

Federated Subscriptions with Router’s HTTP Callback Protocol

Learn GraphQL & Federation with .NET, Java, or TypeScript

Remove Application Logic from Kubernetes Config

GraphQL is for Backend Engineers

GraphQL is the Future for APIs

Past posts

Office Hours: Apollo Server with Trevor Scheer

Modernize your MERN Stack with GraphQL and GraphOS

From Monolith to Federation

Designing the GraphQL schema for Propel, an analytics API platform

Performance impacts of Apollo Router customizations

Add Rust to your GraphQL API with GraphOS

Announcement

Effortless Data Fetching: Introducing Apollo Connectors for REST APIs

More expressive schemas with @oneOf

Federated Subscriptions with Router’s HTTP Callback Protocol

Learn GraphQL & Federation with .NET, Java, or TypeScript

Remove Application Logic from Kubernetes Config

GraphQL is for Backend Engineers

GraphQL is the Future for APIs

Past posts

Office Hours: Apollo Server with Trevor Scheer

Modernize your MERN Stack with GraphQL and GraphOS

From Monolith to Federation

Designing the GraphQL schema for Propel, an analytics API platform

Performance impacts of Apollo Router customizations

Add Rust to your GraphQL API with GraphOS

Stay in our orbit