
<p>Good API programs promote agility and can evolve APIs according to the needs of the business. While it’s important to roll out changes quickly, it cannot come at the expense of reliability. Apollo GraphOS provides workflows to evolve a supergraph safely, including schema checks and insights. These popular features enable API teams to test for breaking changes before rolling out schema updates, allowing them to deliver changes quickly without impacting reliability downstream. We’ve recently shipped significant reliability and usability improvements to schema checks and insights that benefit GraphOS customers. Users now benefit from improved reliability and usability related to input objects, enum types, union types, and interface types.</p>



<h2 class="wp-block-heading" id="Improved-operation-checks-for-interface-and-union-types"><a href="#improved-operation-checks-for-interface-and-union-types" aria-hidden="true" class="aal_anchor" id="improved-operation-checks-for-interface-and-union-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>Improved operation checks for interface and union types</h2>



<p>Previously, any time a user removed an interface from a type, or a type was removed for a union, a schema check would fail for any operation that used that interface or union type, even if the specific type that was removed was not used in the operation. We now do more detailed checks to ensure that we only consider the change as breaking if the operation uses the specific type that was removed.</p>



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



<p>In the past, when you ran an operation check against a variant with no traffic, we would fail the check if we saw any potentially breaking changes. Similarly, a change to a default value of an argument was always considered a breaking change for any operation that used the default. API platform teams now have some additional configuration available to override this default behavior, so that checks run against can be run against variants with no traffic without errors, and default value changes are not considered breaking. Like the other checks configuration, these new options can be enabled per-variant or per-graph.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="239" src="https://wp.apollographql.com/wp-content/uploads/2024/07/image-1024x239.png" alt="" class="wp-image-23822" srcset="https://wp.apollographql.com/wp-content/uploads/2024/07/image-1024x239.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-300x70.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-768x179.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-1200x280.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/07/image.png 1255w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<h2 class="wp-block-heading" id="Improved-usability-of-the-operation-checks-page"><a href="#improved-usability-of-the-operation-checks-page" aria-hidden="true" class="aal_anchor" id="improved-usability-of-the-operation-checks-page"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 usability of the operation checks page</h2>



<p>The operation check page has been a bit difficult to use in the past, especially when a check is run against a lot of operations. To fix this, we’ve given the page a fresh coat of paint, and the checked operations are now shown in a paginated table that can be filtered by status or by operation name or ID. The details of the operation are still just a click away, and they have been given some more real estate to allow you to more easily see the operation details. We have also made some other usability improvements, such as always showing operations that have been checked even if they were previously marked as safe or ignored, as well as providing more details about what was changed in the schema.</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2024/07/video_1280.mp4"></video></figure>



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



<p>In older versions of Apollo Router, operation signatures that appeared in GraphOS had aliases removed and inline input objects replaced with a placeholder empty object. This meant that some operations could not be executed when they were opened in Explorer, and it also hid some useful information. Starting from v1.49.0, you can enable a new experimental config in your router: <code>telemetry.apollo.experimental_apollo_signature_normalization_algorithm: enhanced</code> which configures the router to send aliases and the shape of inline input objects to GraphOS. We still redact all values from the inline input objects, but now you should be able to run operations from the insights page more reliably.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="691" src="https://wp.apollographql.com/wp-content/uploads/2024/07/image-1-1024x691.png" alt="" class="wp-image-23826" srcset="https://wp.apollographql.com/wp-content/uploads/2024/07/image-1-1024x691.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-1-300x203.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-1-768x519.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-1-1200x810.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-1.png 1336w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>Until now, GraphOS has not shown insights on any input object fields or enum values used in operations, and there have been some limitations on operation checks related to enum values and input object types. In Apollo Router v1.50.0 we have introduced a new configuration option for GraphOS Enterprise customers: <code>telemetry.apollo.experimental_apollo_metrics_reference_mode: enhanced</code>. With this option enabled, you will now see insights on all input object fields and enum values that are used in your operations. And with this new data, we are able to mark schema checks as passing if an unused enum value or input object field is removed, or the nullability or default value of an input object field is changed in a safe way.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="514" src="https://wp.apollographql.com/wp-content/uploads/2024/07/image-2-1024x514.png" alt="" class="wp-image-23828" srcset="https://wp.apollographql.com/wp-content/uploads/2024/07/image-2-1024x514.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-2-300x151.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-2-768x386.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/07/image-2.png 1165w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>We hope you can give all these new features a try soon, and if you have any feedback you’d like to provide on them, please let us know!</p>


Enhanced Checks and Observability in GraphOS

How to use Apollo Client with Next.js 13

How to use Apollo Client with Remix

Building a GraphQL server in Go with go-graphql


<p>Two years ago we set out to build Apollo Explorer &#8211; the GraphQL IDE we felt was missing from the GraphQL community. And last summer, we made Explorer available for local development by releasing it in <a href="https://www.apollographql.com/blog/announcement/platform/apollo-sandbox-an-open-graphql-ide-for-local-development/">Apollo Sandbox</a>. But Sandbox still ran on the Apollo Studio domain, and our #1 challenge has been distributing Explorer in a way that gives you enough control over the network properties of your queries. Authentication, CORS, firewalls, you name it – a GraphQL IDE exists to let people write queries, and graph admins need to be able to control the network properties of those HTTP requests, full stop.</p>



<p>We added a lot of controls to Explorer to help. We made a way for graph admins to set default headers on their graphs. We built a mechanism for you to define preflight scripts which can do things like automatically refresh tokens in the headers on your graph. But in the end, we have found that there’s no setting we can add to Studio that can replace what <strong>you</strong> can do with full control over the network requests from our IDE.</p>



<p><strong>That’s why today we are giving Sandbox to <em>you</em>.&nbsp;</strong></p>



<p>We are over the moon to share with you that we have made Apollo Sandbox available for you to <strong>embed on any website</strong>, not just on Apollo Studio. ✨🌙 ✨</p>



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



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



<p>We are now distributing the full-featured code of Apollo Sandbox over a CDN, so you can embed it on any website you’d like. All you need is a little HTML:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-markup">&lt;div id=&quot;sandbox&quot; style=&quot;position:absolute;top:0;right:0;bottom:0;left:0&quot;&gt;&lt;/div&gt;
&lt;script src=&quot;https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
 new window.EmbeddedSandbox({
   target: &quot;#sandbox&quot;,
   // Pass through your server href if you are embedding on an endpoint.
   // Otherwise, you can pass whatever endpoint you want Sandbox to start up with here.
   initialEndpoint: window.location.href,
 });
 // advanced options: https://www.apollographql.com/docs/studio/explorer/sandbox#embedding-sandbox
&lt;/script&gt;</code></pre>



<h3 class="wp-block-heading"><a href="#embed-sandbox-by-default-for-apollo-server" aria-hidden="true" class="aal_anchor" id="embed-sandbox-by-default-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>Embed Sandbox by default for Apollo Server</h3>



<p>If you’re using Apollo Server, you can easily turn on embedding for Sandbox with<a href="https://github.com/apollographql/apollo-server/blob/main/CHANGELOG.md#v380"> a new embed parameter</a> that we released in v3.8.0. This will be the default experience in Apollo Server 4.</p>



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

const server = new ApolloServer({
 ...
 plugins: [
    process.env.NODE_ENV === &quot;production&quot;
      ? ApolloServerPluginLandingPageProductionDefault({
          embed: true,
          graphRef: &quot;plaid-gufzoj@current&quot;
        })
      : ApolloServerPluginLandingPageLocalDefault({ embed: true })
 ]
});</code></pre>



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



<p>We will be releasing a React component for embedded Sandbox that you will be able to import from our <code>@apollo/sandbox</code> package in the near future. We will update this blog post with some example code when it’s available.</p>



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



<p>We know there are a number of GraphQL IDEs to pick from these days&#8230; and we know we’re biased, but we’re particularly excited to bring Sandbox to you because it’s so much more than just an IDE.</p>



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



<p>Over the years, we’ve met many developers who have told us they were scared to restart their computer or clear their browser cookies because they didn’t want to lose their queries in GraphiQL/Playground.</p>



<p>It’s 2022, and we figured that it’s about time for that to be a problem of the past. 🕰️</p>



<p>Connect your local Sandbox to your Studio account to <strong>save operations in the cloud</strong> and never worry about losing your work again.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="609" src="https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt-1024x609.png" alt="" class="wp-image-14169" srcset="https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt-1024x609.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt-300x179.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt-768x457.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt-1536x914.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt-1200x714.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/06/image4-opt.png 1600w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<h3 class="wp-block-heading"><a href="#schema-diffs-checks" aria-hidden="true" class="aal_anchor" id="schema-diffs-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 diffs &amp; checks</h3>



<p>Have you ever worked with a schema so large it was distributed across multiple files or maybe even multiple repos? What about a GraphQL server that generates its schema from code and doesn’t even have an SDL file?</p>



<p>When developing graphs, sometimes all you want is a simple schema diff. But due to the implementation details of our graphs, that’s not always easy to accomplish. So we built it right into Sandbox.</p>



<p>You can diff your local schema against any graph in Apollo Studio, and if the changes look good, you can even run <a href="https://www.apollographql.com/docs/studio/schema-checks">schema checks</a> from Sandbox to make sure they pass CI before checking them into code.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="609" src="https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt-1024x609.png" alt="" class="wp-image-14161" srcset="https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt-1024x609.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt-300x179.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt-768x457.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt-1536x914.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt-1200x714.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/06/image2-opt.png 1600w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>One of the best properties of GraphQL is that it’s self-documenting. We’ve always felt like squashing graph docs alongside a query IDE just didn’t do enough justice to the act of exploring the graph or referencing something in particular. That’s why we built a full-fledged automatic schema reference tool in Studio.</p>



<p>Sandbox also comes with Studio’s schema reference tool:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="609" src="https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized-1024x609.png" alt="" class="wp-image-14163" srcset="https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized-1024x609.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized-300x179.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized-768x457.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized-1536x914.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized-1200x714.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/06/image1-optimized.png 1600w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>And of course, Sandbox has the Apollo Explorer and every feature we’ve built into it over the last several years.<a href="https://www.apollographql.com/docs/studio/explorer/explorer"> Explorer</a> is by far the most sophisticated GraphQL IDE in the ecosystem.</p>



<p>We love Explorer so much because it’s not just a playground for you to query graphs, it’s a playground for us as developers to build the things we always felt were missing from GraphQL tooling. As developers, there’s so much power we’ve gotten used to having in our IDEs and the GraphQL DX is still catching up in a lot of ways. We get new ideas every week about how to improve the Explorer just from using it ourselves.</p>



<p>Explorer has become a passion project of ours, and it is our expression of love for the GraphQL DX itself.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="609" src="https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt-1024x609.png" alt="" class="wp-image-14165" srcset="https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt-1024x609.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt-300x179.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt-768x457.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt-1536x914.png 1536w, https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt-1200x714.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/06/image3-opt.png 1600w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p><strong>That’s all for now folks!</strong></p>



<p>We’re very happy to be bringing this to you today. It’s the culmination of a couple of years of dreaming within the Apollo zoom tunnels, now turned into reality. We’d love to see what you do with Sandbox and where you take your graphs. ❤️</p>



<p>Tweet at us and share what you build! 🐦</p>



<p>As always, happy querying 👋 </p>


How to use Apollo Sandbox on your localhost

How to embed Explorer for a private graph


<p>GraphQL APIs provide data that can be extremely useful to you, your team, or your project. Being able to test and run queries for GraphQL APIs can help you build well-designed queries for your application. Apollo Studio Explorer helps you do this.</p>



<p>This is especially useful when you’re working with large APIs that contain lots of types and fields. The GitHub GraphQL API is one such API. So let’s test out Apollo Studio Explorer by building queries for the GitHub API.</p>



<p>This article will discuss the capabilities of the GitHub GraphQL API. You’ll also get a step-by-step guide on building 3 useful queries. By the end, you’ll be familiar with building queries and using Apollo Studio Explorer.</p>



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



<p>There are a few things you’ll need before diving into this tutorial:</p>



<ul class="wp-block-list">
<li>You have an understanding of what GraphQL is. If you need help with this, check out this <a href="https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/">What is GraphQL</a> article.</li>



<li>You have a GitHub account and an understanding of Git and GitHub features specifically repositories, repository stars, and issues.</li>
</ul>



<p>If you’ve got all this covered, you’re more than ready to jump in! Let’s start by going over the GitHub API and some of its features.</p>



<h2 class="wp-block-heading"><a href="#what-is-the-github-graphql-api" aria-hidden="true" class="aal_anchor" id="what-is-the-github-graphql-api"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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>What Is the GitHub GraphQL API?</strong></h2>



<p>GitHub has a public GraphQL API. Many developers are familiar with how GitHub works so using GitHub’s GraphQL API is a great way to get familiar with GraphQL and Apollo Studio Explorer without having to build your own graph from scratch.</p>



<p>With the GraphQL API, you can&#8230;</p>



<ul class="wp-block-list">
<li>run queries and mutations.</li>



<li>access and mutate data for most of GitHub’s staple features including repositories, users, issues, and much more.</li>



<li>create custom integrations and automate workflows with the data you retrieve.</li>
</ul>



<p>A tool like Explorer can help you navigate the API, quickly build queries, and will help you to take full advantage of all the GitHub API has to offer.</p>



<h2 class="wp-block-heading"><a href="#the-setup" aria-hidden="true" class="aal_anchor" id="the-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><strong>The Setup</strong></h2>



<p>Before we begin building queries, we need to do a few things to get up and running.</p>



<h3 class="wp-block-heading"><a href="#getting-your-github-api-access-token" aria-hidden="true" class="aal_anchor" id="getting-your-github-api-access-token"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 Your GitHub API Access Token</h3>



<p>As mentioned earlier, you need a GitHub account. To access GitHub’s GraphQL API, you’ll also need your personal access token. If you don’t know how to retrieve that, check out this <a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token" target="_blank" rel="noreferrer noopener">guide on creating personal access tokens</a>. When you’re choosing permissions, you only need to select <strong>repo.</strong> Once you have your token, be sure to save it for later use and DO NOT share with anyone.</p>



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



<p>To run the GitHub API in Apollo Studio Explorer, you’ll need to authenticate your API requests using the access token you retrieved in the previous section.</p>



<p>Navigate to the <a href="https://studio.apollographql.com/public/github/home?variant=current&amp;referrer=blog">GitHub API home page in Apollo Studio</a>. Click the <strong>Run in Explorer</strong> button located in the top right-hand corner.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1000" height="474" src="https://wp.apollographql.com/wp-content/uploads/2022/03/GTIHUBAPIEXPLORER.gif" alt="Click Run in Explorer button in Apollo Studio Explorer
" class="wp-image-12351"/></figure>



<p>Before you can test and run queries, you’ll need to add your token as a <strong>Header</strong>. Click <strong>+New Header</strong> and select <strong>Authorization</strong>. In the next field type <code>bearer</code> followed by your access token. It should look like <code>bearer XX-GH-PERSONAL-ACCESS-TOKEN-XX</code></p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="483" src="https://wp.apollographql.com/wp-content/uploads/2022/03/Group-1-1024x483.png" alt="Add Authentication headers with the GitHub access token as the value
" class="wp-image-12358" srcset="https://wp.apollographql.com/wp-content/uploads/2022/03/Group-1-1024x483.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/03/Group-1-300x142.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/03/Group-1-768x362.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/03/Group-1-1200x566.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/03/Group-1.png 1439w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Notice that the first pre-filled header is deselected.</p>



<p>With authentication out the way, let’s test out the API and Explorer by building some queries.</p>



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



<p>The GitHub API is massive and there is so much data available. In this tutorial, we’ll focus on retrieving information about your repositories. We want to create a query that will return all of your repositories, return the number of stars for a repository that you search by name, and return open issues for a repository that you search by name.</p>



<p>First, start by deleting all the preselected fields.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="600" height="272" src="https://wp.apollographql.com/wp-content/uploads/2022/03/GITHUBAPIREMOVEFIELDS.gif" alt="Remove preselected fields in Apollo Studio Explorer
" class="wp-image-12360"/></figure>



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



<p>To retrieve the names of your repositories, your query will look like this:</p>



<pre class="wp-block-code"><code>&lt;meta charset=&quot;utf-8&quot;&gt;query getRepositories($last: Int, $isFork: Boolean) {
  viewer {
    repositories(last: 10, isFork: false) {
      nodes {
        name
      }
    }
  }
}</code></pre>



<p>The query is named <code>getRepositories</code>. (You can change the name if you like). The <code>viewer</code> field holds information about your GitHub account including <code>repositories</code>. We need to include <code>last</code> and <code>isFork</code> as arguments. The <code>last</code> argument takes an integer and indicates the number of repositories that will be returned to you. The <code>isFork</code> argument is defined by a boolean and determines if the repositories returned will be forked repositories or not. In this example, <code>last</code> is set to 10 and <code>isFork</code> is set to false.</p>



<p>There is a lot of data available in <code>repositories</code> but to get the names of your repositories, you need to access <code>nodes</code> and <code>names</code> which is a field within <code>nodes</code>. Your query is complete and now you can run it to see your repository names being returned.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1000" height="520" src="https://wp.apollographql.com/wp-content/uploads/2022/03/GITHUBAPIRUNQUERY.gif" alt="Click run query button in Apollo Studio Explorer
" class="wp-image-12363"/></figure>



<h3 class="wp-block-heading"><a href="#building-a-query-that-returns-your-repository-stars" aria-hidden="true" class="aal_anchor" id="building-a-query-that-returns-your-repository-stars"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 query that returns your repository stars</h3>



<p>To retrieve the number of stars on a repository that you search by name, this is what your query will look like:</p>



<pre class="wp-block-code"><code>query getRepostioryStars($name: String!, $owner: String!){
  repository(name: &quot;repo-name&quot;, owner: &quot;repo-owner&quot;) {
    stargazerCount
  }
}
</code></pre>



<p>The query is named <code>getRepositoryStars</code>. The <code>repository</code> field contains data about a repository that you search by name and owner. You specify what repository you want data for by defining the <code>name</code> and <code>owner</code> arguments. Finally, the <code>stargazerCount</code> returns an integer which will be the number of stars on the repository you previously specified.</p>



<p>Your query is complete and you can run it in Explorer to see how many stars your repository has.</p>



<h3 class="wp-block-heading"><a href="#building-a-query-that-returns-your-repository-issues" aria-hidden="true" class="aal_anchor" id="building-a-query-that-returns-your-repository-issues"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 query that returns your repository issues</h3>



<p>You would use the following query to retrieve the open issues of a repository that you search by name:</p>



<pre class="wp-block-code"><code>query getIssues($name: String!, $owner: String!, $last: Int, $states: &#091;IssueState!]){
  repository(name: &quot;repo-name&quot;, owner: &quot;repo-owner&quot;) {
    issues(last: 10, states:OPEN) {
      edges {
        node {
          author {
            login
          }
          title
          url
          publishedAt
        }
      }
    }
  }
}
</code></pre>



<p>This query is called <code>getIssues</code>. You worked with <code>repository</code> already. Just remember to replace <code>repo-name</code> and <code>repo-owner</code> with the name of the repository you’re interested in and your GitHub username respectively. The <code>issues</code> field is selected and it has <code>last</code> and <code>states</code> are arguments. You’ll want to pull the last 10 open issues so set <code>last</code> to <code>10</code> and <code>states</code> should be <code>OPEN</code>. The data we want is within <code>edges</code> and <code>node</code>.</p>



<p>Within <code>node</code>, there are a few pieces of information you’ll need. The issue author name is important. The <code>author</code> field and <code>login</code> subfield will give you that information. The title of the issue and the date it was made are also valuable. You might also want the URL to the issue. You can get this information with <code>title</code>, <code>urll</code>, and <code>publishedAt</code>, all of which are subfields of <code>node</code>.</p>



<p>Your query for retrieving repository issues is complete. You can run it to see the information the API will return to you.</p>



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



<p>By now, you’ve gotten more familiar with Apollo Studio Explorer by building and testing queries with GitHub GraphQL API. What can you do next?</p>



<p>If you&#8217;d like to try the queries outlined in this article yourself, you can easily access them in this <a href="https://studio.apollographql.com/public/github/explorer?collectionId=93aef769-11bb-470d-abec-855dd45aed93&amp;overlay=view-collection-details&amp;variant=current">Operations Collection</a>. Operations Collection is a new feature we recently released that enables you to save, organize, and share your graph&#8217;s frequently used GraphQL operations. You can read about them more in <a href="https://www.apollographql.com/blog/announcement/platform/save-and-share-your-graphql-operations-in-apollo-explorer/">this blog post announcement</a>.</p>



<p>If you want to improve your GraphQL knowledge, check out this <a href="https://odyssey.apollographql.com/?referrer=blog">free and interactive GraphQL training course.</a> You can learn more about Explorer and its features with our <a href="https://www.apollographql.com/docs/studio/explorer/explorer/">guide to getting started with Explorer</a>.</p>


Using the GitHub GraphQL API with Apollo Studio Explorer

Using GraphQL with Python – A Complete Guide

Testing Apollo Client Applications

TypeScript GraphQL Code Generator – Generate GraphQL Types with Apollo Codegen Tutorial


<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="(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="(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="(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="(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="(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="(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="(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="(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="(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="(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

What is a GraphQL query? GraphQL query examples using Apollo Explorer


<p>If you&#8217;re using Apollo Android, the chances are that you are using a <code>schema.json</code> file: an&nbsp;<a rel="noreferrer noopener" target="_blank" href="https://graphql.org/learn/introspection/"><strong><u>introspection</u></strong></a>&nbsp;schema. While introspection schemas work well, GraphQL has&nbsp;<a rel="noreferrer noopener" target="_blank" href="https://graphql.org/learn/schema/"><strong><u>SDL</u></strong></a>&nbsp;(Schema Definition Language), which is another, more concise, way to describe a schema.&nbsp;</p>



<p>The excellent news is that Apollo Android supports SDL! </p>



<p>Read below to learn more about SDL and how to enable it in your project.</p>



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



<p>Since Apollo Android already supports introspection schemas, why bother with a new schema format? Well, there are a ton of reasons for that:</p>



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



<p>Taking a look at the&nbsp;<a target="_blank" href="https://github.com/apollographql/apollo-android/pull/2543" rel="noreferrer noopener"><u>commit</u></a>&nbsp;that moved the Apollo Android test schema from introspection to SDL:&nbsp;</p>



<p>&nbsp;The SDL file has almost ten times fewer lines. It&#8217;s also significantly smaller (<a rel="noreferrer noopener" target="_blank" href="https://github.com/apollographql/apollo-android/blob/5d8338338cff6217a73f5c62db2443bf1d760577/apollo-compiler/src/test/graphql/schema.sdl"><u>9KB</u></a>&nbsp;vs.&nbsp;<a rel="noreferrer noopener" target="_blank" href="https://github.com/apollographql/apollo-android/blob/02d77acd9d84dc7fb4cf8d78e2b602beec7cf185/apollo-compiler/src/test/graphql/schema.json"><u>106KB</u></a>), making your repository faster to download.</p>



<h3 class="wp-block-heading"><a href="#2-sdl-is-easier-to-read-and-write" aria-hidden="true" class="aal_anchor" id="2-sdl-is-easier-to-read-and-write"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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. SDL is easier to read (and write!)</h3>



<p>SDL being smaller also means it&#8217;s easier to read. Let&#8217;s take an example from our&nbsp;<a rel="noreferrer noopener" target="_blank" href="https://github.com/apollographql/starwars-server"><u>favorite schema</u></a>&nbsp;(simplified here):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql"># SDL
&quot;&quot;&quot;A character from the Star Wars universe&quot;&quot;&quot;
interface Character {
  &quot;&quot;&quot;The ID of the character&quot;&quot;&quot;
  id: ID!

  &quot;&quot;&quot;The name of the character&quot;&quot;&quot;
  name: String!

  &quot;&quot;&quot;The date character was born.&quot;&quot;&quot;
  birthDate: Date!
}</code></pre>



<p>The same thing in JSON (with only the &#8220;id&#8221; field or it would take too much space!):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">// Introspection
{
  &quot;kind&quot;: &quot;INTERFACE&quot;,
  &quot;name&quot;: &quot;Character&quot;,
  &quot;description&quot;: &quot;A character from the Star Wars universe&quot;,
  &quot;fields&quot;: [
    {
      &quot;name&quot;: &quot;id&quot;,
      &quot;description&quot;: &quot;The ID of the character&quot;,
      &quot;args&quot;: [],
      &quot;type&quot;: {
        &quot;kind&quot;: &quot;NON_NULL&quot;,
        &quot;name&quot;: null,
        &quot;ofType&quot;: {
          &quot;kind&quot;: &quot;SCALAR&quot;,
          &quot;name&quot;: &quot;ID&quot;,
          &quot;ofType&quot;: null        }
      },
      &quot;isDeprecated&quot;: false,
      &quot;deprecationReason&quot;: null    },
    {
      [REDACTED],
    }
  ]
}</code></pre>



<p>Adding a new field to an SDL type is a few lines, and you won&#8217;t have to worry about creating a valid JSON document or nesting the <code>LIST</code> and <code>NON_NULL</code> types; this makes the experience of writing unit tests for Apollo Android way more enjoyable.</p>



<h3 class="wp-block-heading"><a href="#3-introspection-isnt-always-an-option" aria-hidden="true" class="aal_anchor" id="3-introspection-isnt-always-an-option"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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. Introspection isn&#8217;t always an option</h3>



<p>While introspection is a useful tool during development, it exposes your schema&#8217;s structure to anyone to access your GraphQL endpoint. Unfortunately, exposing your schema can have security repercussions, and a lot of server implementations like apollo-server&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/" rel="noreferrer noopener"><u>will disable introspection in production</u></a>, making it harder to obtain an introspection schema.</p>



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



<p>Last but not least, SDL carries more information than plain introspection JSON. Custom directives definition, for example, are stripped out in introspection responses. While Apollo Android does not use this, having this information gives client developers more context about the schema they are using. There are other useful ways we could utilize it in the future too!&nbsp;</p>



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



<p>Using SDL in Apollo Android is&nbsp;<strong>as simple as replacing your <code>schema.json</code> file with a <code>schema.sdl</code> file</strong>. You might sometimes see this file named schema.graphql. We decided to go with the explicit <code>schema.sdl</code> name to distinguish from operation files, which also have a .graphql extension.&nbsp;</p>



<p>We also built a few tools in the Gradle plugin to make it easier to work with SDL files:</p>



<h3 class="wp-block-heading"><a href="#transforming-an-introspection-schema-to-a-sdl-schema" aria-hidden="true" class="aal_anchor" id="transforming-an-introspection-schema-to-a-sdl-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>Transforming an introspection schema to a SDL schema</h3>



<p>The Gradle plugin in Apollo Android can automatically translate your <code>schema.json</code> to <code>schema.sdl</code>:</p>



<p><code>./gradlew convertApolloSchema --from schema.json --to schema.sdl</code></p>



<p>Note that it works both ways if for some reason you want to get a JSON file:</p>



<p><code>./gradlew convertApolloSchema --from schema.sdl --to schema.json</code></p>



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



<p>Since the plugin can translate between both formats, it can save the results of an introspection query as SDL.</p>



<p><code>./gradlew downloadApolloSchema --endpoint https://example.com/graphql --schema app/src/main/graphql/com/example/schema.sdl</code></p>



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



<p>Finally, if you have a Studio integration, you can also download the SDL directly from<a target="_blank" href="https://www.apollographql.com/docs/studio/" rel="noreferrer noopener"><u>&nbsp;Apollo Studio</u></a>. Get your&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/studio/api-keys/" rel="noreferrer noopener">API key</a>&nbsp;and type:</p>



<p><code>./gradlew downloadApolloSchema --key $API_KEY --graph $GRAPH --variant current&nbsp;</code><br><code>--schema app/src/main/graphql/com/example/schema.sdl</code></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>The initial SDL support was <a href="https://github.com/apollographql/apollo-android/commit/8fccd52b01b7f8e9a7d9dffca0438cb8c97da141">committed</a> a couple of months ago and we’re still working on improving it. <code>convertApolloSchema</code>, for example, is a very recent addition.</p>



<p>It’s still the early days of SDL support for Apollo Android but we’ve been using it successfully to write a lot of unit tests and it really made our life better. We hope it can make yours better too!</p>



<p>Try it out and <a href="https://app.slack.com/client/T09229ZC6/C01A6KM1SBZ">let us know</a> how you liked it!</p>


SDL Support in Apollo Android


<p>One of the most common use cases front-end developers face is re-render the UI after executing a <code>mutation</code> and changing something in the backend.</p>



<p>To solve this problem, a lot of developers like to use the <code>refetchQueries</code> API.</p>



<p>For example, if I wanted to <strong>add</strong> a <code>todo</code> to a list of <code>todos</code>, I might pass a <code>GET_ALL_TODOS</code> query to my list of queries to refetch, like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as AddTodoTypes from &#039;./__generated__/AddTodo&#039;;
import { GET_ALL_TODOS } from &quot;../queries/getAllTodos&quot;;

export const ADD_TODO = gql`
  mutation AddTodo ($text: String!) {
    addTodo (text: $text) {
      success
      error {
        message
      }
    }
  }
`

export function useAddTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    AddTodoTypes.AddTodo, 
    AddTodoTypes.AddTodoVariables
  &gt;(
    ADD_TODO,
    {
      refetchQueries: [
        { query: GET_ALL_TODOS }
      ]
    }
  )
  return { mutate, data, error };
}
﻿</code></pre>



<p>While this approach works, the biggest disadvantage is that we have to make multiple network round-trips to get our UI to re-render, even if we already have the data we need on the client-side.</p>



<p>It also introduces the question of &#8220;what do we do if we have a lot of queries relying on the same data? Do we have to remember to add all of <em>those</em> to the same <code>refetchQueries</code> list as well?&#8221;</p>



<p>Luckily, you don&#8217;t.</p>



<p>In this post, I&#8217;ll explain when it makes sense to use <code>refetchQueries</code>, and when you should rely on Apollo Client&#8217;s automatic cache normalization algorithm or <code>update</code> functions.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>The following example uses the Apollo Client 3 Todos app example from <a href="https://github.com/apollographql/ac3-state-management-examples">@apollographql/ac3-state-management-examples</a>.</p></blockquote>



<h2 class="wp-block-heading"><a href="#use-refetchqueries-when-youre-first-getting-started" aria-hidden="true" class="aal_anchor" id="use-refetchqueries-when-youre-first-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>Use refetchQueries when you&#8217;re first getting started</h2>



<p>If you&#8217;re just getting started with GraphQL, I think the mental model of passing in the queries that you&#8217;d like to re-run after a mutation is an easy one to wrap your head around.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-1024x789.png" alt="" class="wp-image-5972" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM.png 1061w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Looking back at our trivial <code>todo</code> app, if we have a list of <code>todos</code> and we want to <strong>add</strong> an item, we can accomplish that and re-render the UI with the <code>ADD_TODO</code> operation passed into a <code>useMutation</code> hook and the <code>GET_ALL_TODOS</code> query passed into the <code>refetchQueries</code> array.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const [mutate, { data, error }] = useMutation&lt;
  AddTodoTypes.AddTodo, 
  AddTodoTypes.AddTodoVariables
&gt;(
  // Execute this
  ADD_TODO, 
  {
    // Then re-run 
    refetchQueries: [
      { query: GET_ALL_TODOS }
    ]
  }
)
return { mutate, data, error };
﻿</code></pre>



<p>This works. It runs the query and after successfully completing the mutation, it executes the <code>GET_ALL_TODOS</code> query and pulls in all the new <code>todos</code>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-1024x789.png" alt="" class="wp-image-5976" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM.png 1061w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>The advantage here is that this approach is straightforward. The disadvantage is that we&#8217;re fetching the entire list of data again when we might not need to.</p>



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



<p>For a more efficient use of bandwidth and network round-trips, we can rely on cache normalization and <code>update</code> functions.</p>



<p>As we previously learned in the &#8220;<a href="https://www.apollographql.com/blog/demystifying-cache-normalization/">Demystifying Cache Normalization</a>&#8221; blog post, for certain operations, the Apollo Client cache is smart enough to <strong>automatically update the cache for you</strong>. For others, we can utilize an <code>update</code> function to tell the cache how we want it to update.</p>



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



<p>For mutations that <strong>change only a single entity,</strong> the cache is smart enough to update the item in place automatically, but only if we return the changed item (containing the unique identifier) in the mutation response.</p>



<p>Here&#8217;s an example of <strong>editing a</strong> <code>todo</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as EditTodoTypes from &#039;./__generated__/EditTodo&#039;

export const EDIT_TODO = gql`
  mutation EditTodo ($id: Int!, $text: String!) {
    editTodo (id: $id, text: $text) {
      success
      todo { # Return the new todo in the mutation response
        id
        text 
        completed
      }
      error {
        ... on TodoNotFoundError {
          message
        }
        ... on TodoValidationError {
          message
        }
      }
    }
  }
`

export function useEditTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    EditTodoTypes.EditTodo, 
    EditTodoTypes.EditTodoVariables
  &gt;(
    EDIT_TODO
  )

  return { mutate, data, error };
}
﻿</code></pre>



<p>And since we&#8217;ve returned the <strong>changed data</strong> in the <code>mutation</code> response, it works.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-1024x789.png" alt="" class="wp-image-5980" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM.png 1061w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>But for other operations, like <em>adding</em> to a list or <em>removing</em> elements from a list, we need to give the cache a little bit of help to figure out exactly what we want to do.</p>



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



<p>Here&#8217;s the <code>ADD_TODO</code> example again, but this time using an <code>update</code> function to update the existing list of <code>todos</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as AddTodoTypes from &#039;./__generated__/AddTodo&#039;;
import { GET_ALL_TODOS } from &quot;../queries/getAllTodos&quot;;
import { GetAllTodos } from &quot;../queries/__generated__/GetAllTodos&quot;;

export const ADD_TODO = gql`
  mutation AddTodo ($text: String!) {
    addTodo (text: $text) {
      success
      todo {
        id
        text 
        completed
      }
      error {
        message
      }
    }
  }
`

export function useAddTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    AddTodoTypes.AddTodo, 
    AddTodoTypes.AddTodoVariables
  &gt;(
    ADD_TODO,
    {
      update (cache, { data }) {
        // We use an update function here to write the 
        // new value of the GET_ALL_TODOS query.
        const newTodoFromResponse = data?.addTodo.todo;
        const existingTodos = cache.readQuery&lt;GetAllTodos&gt;({
          query: GET_ALL_TODOS,
        });

        if (existingTodos &amp;&amp; newTodoFromResponse) {
          cache.writeQuery({
            query: GET_ALL_TODOS,
            data: {
              todos: [
                ...existingTodos?.todos,
                newTodoFromResponse,
              ],
            },
          });
        }
      }
    }
  )
  return { mutate, data, error };
}
﻿</code></pre>



<p>In this example, we use the <code>readQuery</code> and <code>writeQuery</code> APIs to write the new value of the <code>todos</code> list which contains the <code>todo</code> we created in the <code>mutation</code>.</p>



<p>One way we could omit needing to write this <code>update</code> function is if the mutation response returned the <strong>entire list of new todos</strong> in the <code>mutation</code> response, but that&#8217;s not always possible.</p>



<p>Sometimes you don&#8217;t own the API.</p>



<p>Sometimes, it can get expensive to be doing that after every <code>mutation</code>.</p>



<p>So here, we utilize the <code>update</code> function.</p>



<p>Admittedly, this is a little bit more work than using <code>refetchQueries</code>, but that&#8217;s the trade off for a performance improvement. You don&#8217;t have to re-request the same data from your server and wait for another entire roundtrip to update the UI.</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 summary best times to use <code>refetchQueries</code> are:</p>



<ol class="wp-block-list"><li>When you don&#8217;t yet know how ACC normalization works</li><li>If you&#8217;re not able to return the changed data in a mutation response</li></ol>



<p>To reduce round-trips after mutations, we generally recommend relying on the Apollo Client automatic caching normalization and when necessary, <code>update</code> functions.</p>



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



<ul class="wp-block-list"><li>&#8220;<a href="https://www.apollographql.com/blog/demystifying-cache-normalization/">Demystifying Cache Normalization</a>&#8221; from the Apollo Blog</li><li>&#8220;<a href="https://www.apollographql.com/docs/react/caching/advanced-topics/#updating-after-a-mutation">Updating after a Mutation</a>&#8221; from the Apollo Docs</li></ul>


When To Use Refetch Queries in Apollo Client


<p>On this blog, we spend a lot of time pushing the limits of GraphQL and talking about some of the most advanced parts of the technology. However, GraphQL is inherently quite simple, and works just fine without any specialized tooling. So let’s demonstrate that by showing several very simple ways of calling a GraphQL API over HTTP.</p>



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



<p>For this post, we&#8217;ll rely on the simple <code>todos</code> API from <a href="https://github.com/apollographql/ac3-state-management-examples">apollographql/ac3-state-management-examples</a>.</p>



<p>Let&#8217;s clone the repo, install the dependencies, and start the server locally.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">git clone git@github.com:apollographql/ac3-state-management-examples.git
cd ac3-state-management-examples/apollo-remote-state/server
npm install
npm run start</code></pre>



<p>If all goes well, you should see a message letting you know that your GraphQL server is up and running.</p>



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



<h2 class="wp-block-heading" id="e5a3"><a href="#1-using-graphql-ides-apollo-explorer" aria-hidden="true" class="aal_anchor" id="1-using-graphql-ides-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>1. Using GraphQL IDEs (Apollo Explorer)</h2>



<p>GraphQL IDEs let you build queries, browse schemas, and test out GraphQL APIs.</p>



<p><a href="http://studio.apollographql.com/dev?referrer=blog" data-type="URL" data-id="http://studio.apollographql.com/dev?referrer=blog">Apollo Explorer</a> is a free cloud-based GraphQL IDE that comes with one-click query building, intelligent search, and a multitude of other productivity features to solve common pain-points we&#8217;ve heard from developers building apps with GraphQL.</p>



<p>Getting started should be faster than making a pot of coffee.</p>



<p>To use the explorer, we&#8217;ll head to <a href="http://studio.apollographql.com/dev?referrer=blog">studio.apollographql.com/dev</a> and create an account (using either GitHub or your email).</p>



<p>Finally, choose a name for your graph, select the “Development” graph type, add your localhost endpoint (Apollo Server’s default is <a href="http://localhost:4000">http://localhost:4000</a>), and click “Create Graph”.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="935" src="https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM-1024x935.png" alt="" class="wp-image-6275" srcset="https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM-1024x935.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM-300x274.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM-768x701.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM-1536x1402.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM-1200x1095.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-03_at_10.48.40_PM.png 1814w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>And that’s it! You’re ready to start querying.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="241" src="https://wp.apollographql.com/wp-content/uploads/2020/12/ezgif-4-e8f283a9e165.gif" alt="" class="wp-image-6343"/></figure>



<p>Here&#8217;s a query you can use to get started. Paste this into the <em>Operations</em> window and click the blue button to run the query.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query AllTodos {
  todos {
    edges {
      node {
        completed
        id
        text
      }
    }
  }
}</code></pre>



<p>The Explorer is really useful! Not only is it easy to use, but we can see how long it took for the query to execute, download the responses, and keep track of all the operations you ran over time.</p>



<p>I don&#8217;t want to give you the impression that you need a specialized tool to access data from your GraphQL API. You don&#8217;t 😇. Let’s go way back to basics.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p>By the way, some other GraphQL IDEs you can check out are: Graph<em>i</em>QL, GraphQL Playground, and Insomnia.</p>
</blockquote>



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



<p>curl is one of the most popular tools for accessing HTTP endpoints from the command line. It’s often used as a lowest-common-denominator example for how to access an API without any programming language or specialized tooling. So let’s use it to fetch GraphQL data!</p>



<p>Since curl is a command line tool, it’s easier to operate with queries that are just one line, so we’ll use the short one from above.&nbsp;Without further ado, here’s a curl command that will fetch a GraphQL query from our API:</p>



<pre class="wp-block-preformatted">curl \
-X POST \
-H "Content-Type: application/json" \
--data '{ "query": "{ todos { edges { node { id completed text } } } }" }' \
http://localhost:4000/</pre>



<p>It specifies four things about our request:</p>



<ol class="wp-block-list">
<li><strong>The</strong> <code>POST</code> <strong>HTTP verb</strong>, which is the most common one used by GraphQL APIs (although usually&nbsp;<a rel="noreferrer noopener" href="http://dev.apollodata.com/tools/apollo-server/requests.html" target="_blank">GET is also supported</a>)</li>



<li><strong>The content type of&nbsp;</strong><code>application/json</code>, because we’re specifying the query as part of a JSON object</li>



<li><strong>The data sent</strong>, which is a JSON document that looks like:&nbsp;<code>{ &quot;query&quot;: &quot;{ todos { edges { node { id completed text } } } }&quot; }</code>. This JSON wrapper is helpful because you can also specify other options, like dynamic variables as part of the JSON object.</li>



<li><strong>The actual URL of the GraphQL endpoint</strong>, in this case <code>http://locahost:4000</code></li>
</ol>



<p>And that’s all! Using the above options, you can query nearly any GraphQL API, for example, <a rel="noreferrer noopener" href="https://twitter.com/trevorblades" target="_blank">Trevor Blades</a>&#8216; <a rel="noreferrer noopener" href="http://countries.trevorblades.com/" target="_blank">countries API</a>, which I love to use to introduce people to GraphQL for the first time:</p>



<pre class="wp-block-preformatted">curl \
-X POST \
-H "Content-Type: application/json" \
--data '{ "query": "{ countries { code name } } " }' \
https://countries.trevorblades.com/</pre>



<p>Alright great, so we’ve found a completely vanilla way to send requests. For more details about exactly how GraphQL queries work, read <a rel="noreferrer noopener" href="https://twitter.com/stubailo" target="_blank">Sashko Stubailo</a>&#8216;s post, <a rel="noreferrer noopener" href="https://dev-blog.apollodata.com/the-anatomy-of-a-graphql-query-6dffa9e9e747" target="_blank">“The Anatomy of a GraphQL Query.</a></p>



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



<p>You can make a GraphQL HTTP request in literally any programming language, as long as you can set the above 4 parts correctly. So let’s convert that curl request into some JavaScript code with&nbsp;<code>fetch</code>, the new standard for getting HTTP results with promises. This will work in modern browsers with no libraries, but will require a polyfill in Node and&nbsp;<a rel="noreferrer noopener" href="http://caniuse.com/#search=Fetch" target="_blank">some browsers</a>. Let’s check out the code:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">require(&#039;isomorphic-fetch&#039;);

fetch(&#039;http://localhost:4000&#039;, {
  method: &#039;POST&#039;,
  headers: { &#039;Content-Type&#039;: &#039;application/json&#039; },
  body: JSON.stringify({ query: `
    query {
      todos {
        edges {
          node {
            completed
            id
            text
          }
	}
      }
    }` 
  }),
})
.then(res =&gt; res.json())
.then(res =&gt; console.log(res.data));</code></pre>



<p>If you run this code Chrome&#8217;s DevTools, you&#8217;ll notice that the following output is printed to the console.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="599" height="89" src="https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-06_at_1.09.08_PM.png" alt="" class="wp-image-6287" srcset="https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-06_at_1.09.08_PM.png 599w, https://wp.apollographql.com/wp-content/uploads/2020/12/Screen_Shot_2020-12-06_at_1.09.08_PM-300x45.png 300w" sizes="(max-width: 599px) 100vw, 599px" /></figure>



<p>Neat, right? As you can see, the way we request GraphQL data using Fetch is pretty similar to the request we constructed with curl, but there are a few things here that would become pretty repetitive if we had to type them out every time. Not only that, but to effectively work with GraphQL data in most applications, you&#8217;ll likely want to cache it, display the data somehow, and re-render your view when it changes.</p>



<p>That sounds like something that a GraphQL client can help us with.</p>



<h2 class="wp-block-heading" id="e15f"><a href="#4-using-graphql-clients-apollo-client" aria-hidden="true" class="aal_anchor" id="4-using-graphql-clients-apollo-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>4. Using GraphQL clients (Apollo Client)</h2>



<p>GraphQL client libraries are meant to help us work with more effectively build fully-fledged applications with GraphQL data.</p>



<p><a href="https://www.apollographql.com/docs/react/">Apollo Client</a> handles the entire data-fetching and state management part of working with GraphQL data- we just need to hook it up and write the queries!</p>



<p>For example, if you&#8217;re building a React application, one of the most popular ways to query data using Apollo Client is to use the <code>useQuery</code> hook. Let&#8217;s demonstrate how we could fetch all the <code>todos</code> and display them in a list.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import React from &#039;react&#039;
import { gql, useQuery } from &#039;@apollo/client&#039;

const GET_ALL_TODOS = gql`
  query GetAllTodos {
    todos {
      edges {
        node {
	  completed
	  id
	  text
	}
      }
    }
`;

export const Todos = () =&gt; {
  const { loading, error, data } = useQuery(GET_ALL_TODOS);

  if (loading) return &#039;Loading...&#039;;
  if (error) return `Error! ${error.message}`;

  return (
    &lt;ul&gt;
      { data.todos.edges.map((edge, i) =&gt; (
        &lt;li key={edge.node.id}&gt;{edge.node.text}&lt;/li&gt;
      ))}
    &lt;/ul&gt;
  )
}</code></pre>



<p>Passing the GraphQL query to the <code>useQuery</code> hook gives us an object that can be de-structured into <code>loading</code>, <code>error</code>, and <code>data</code> objects. If the query successfully executes and returns the GraphQL data from the server, we can map over the response <code>data</code> and display the elements in a list. Sweet!</p>



<p>To learn more about Apollo Client and how to set it up in your project, check out the <a href="https://www.apollographql.com/docs/react/get-started/">getting started docs</a>.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p>If you&#8217;re an iOS or Android developer, you can use the <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/ios/" target="_blank">Apollo iOS</a> and <a rel="noreferrer noopener" href="https://github.com/apollographql/apollo-android" target="_blank">Apollo Android</a> GraphQL clients which give you type-safe APIs to work with GraphQL servers.</p>
</blockquote>



<h2 class="wp-block-heading" id="ef7b"><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>Because GraphQL operates over HTTP, you can use any language, client library, or tool to fetch GraphQL data so long as you format the HTTP request properly. If you&#8217;re just getting started with GraphQL, I recommend using a tool like <a href="http://studio.apollographql.com/dev?referrer=blog" target="_blank" rel="noreferrer noopener">Apollo Explorer</a> that&#8217;ll help you understand how to structure requests and explore your schema. And if you&#8217;re getting ready to build a web application that relies on GraphQL data, try out a GraphQL client library like <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/react/" target="_blank">Apollo Client</a>; it saves you time by handling the mundane parts of app development, and lets you focus on coding the parts that makes your app special.</p>



<hr class="wp-block-separator has-css-opacity"/>



<p>Special thanks to <a rel="noreferrer noopener" href="https://twitter.com/stubailo" target="_blank">Sashko Stubailo</a> who wrote the first version of this blog post nearly three years ago! Follow him on Twitter at <a rel="noreferrer noopener" href="https://twitter.com/stubailo" target="_blank">@stubailo</a>.</p>


4 Simple Ways to Call a GraphQL API

Add GraphQL to Your Jetpack Compose Apps


<p>GraphQL helps us build apps faster. Data is more discoverable, easier to query, change, and evolve over time. Most companies that adopt GraphQL typically take one of these four patterns:</p>



<ul class="wp-block-list"><li><strong>Client-only:</strong> Client teams that are excited to take advantage of GraphQL’s client-centric data-fetching capabilities may add a GraphQL API within their own application for the convenience of wrapping other APIs.</li><li><strong>Backend for Frontend (BFF):</strong> BFFs add a new layer to the stack so each client (for example, web or iOS) can send queries to a service that is tightly coupled to its specific user experience. GraphQL can be a natural fit for building out this intermediary layer.</li><li><strong>Monolith:</strong> A company may develop a single, large GraphQL API for all client to use with either shared ownership between teams or with a dedicated team to manage this API.</li><li><strong>Multiple overlapping graphs:</strong> Different teams within a company may develop their own service-specific GraphQL APIs. Teams usually try to split these APIs by types or use cases, but there is often some amount of overlap between the graphs.</li></ul>



<p>Each of these approaches to running a graph in production can get you up and running and are great first steps toward leveraging GraphQL’s benefits across a company.<br><br>However, over the last few years we’ve spent helping companies like Glassdoor, PayPal, Expedia and NYT to design, improve, and scale their GraphQL efforts, <strong>we&#8217;ve realized that each of these architectures break down over time and create pain points when trying to consolidate and scale GraphQL across teams.</strong><br><br>That&#8217;s why we&#8217;re writing the <em>GraphQL at Enterprise Scale</em> free ebook: to teach you how to scale GraphQL in the Enterprise with Federation and Apollo Studio.</p>



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



<p>The first version of the book just launched today! You can download it at <a href="https://www.apollographql.com/guide">apollographql.com/guide</a>. It covers advanced topics like:</p>



<ul class="wp-block-list"><li>The most common pre-consolidation GraphQL patterns and where they <strong>break down</strong> over time</li><li>How Federation help you scale APIs, get a unified view of your data, leverage existing infrastructure, and ship code faster</li><li>When to consolidate your GraphQL efforts with Federation</li><li>The role that GraphQL champions play in helping your company serve your graph as a product</li></ul>



<h2 class="wp-block-heading"><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 only the first version! In future updates to the book, we&#8217;ll explore:</p>



<ul class="wp-block-list"><li>How to migrate from a monolith, BFF, overlapping graphs, or client-side only GraphQL data layer to Federation</li><li>How to understand, plan, and design a Federated graph for your clients</li><li>Strategies for caching GraphQL data</li><li>Advanced testing patterns</li><li>How to monitor your graph performance</li><li>and so much more!</li></ul>



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



<p>If you download the current version of the book, we&#8217;ll keep you posted as to when we publish new chapters.</p>



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



<p>We&#8217;re really excited about this resource. If you have a topic you&#8217;re struggling with or you&#8217;d like to learn more about specifically, feel free to reach out to us at <a href="mailto:solutions@apollographql.com">solutions@apollographql.com</a>.<br><br>If you need our advice on scaling your GraphQL efforts <em>today</em>, we&#8217;d love to hear from you.<br><br><a href="https://www.apollographql.com/contact-sales">Click here to contact sales</a>.<br>Happy querying!</p>


Announcing the GraphQL at Enterprise Scale Guide [Free Ebook]

Building a Portable Apollo Server Config

Dispatch This: Using Apollo Client 3 as a State Management Solution


<p>The Apollo community is made up of developers around the world building client-side experiences on top of the data graph.</p>



<p>If you’re as excited about the data graph as we are, one of the best ways to help the community is to write about your experience! We love community blog posts, and we’d love to work with you to get your post published on the&nbsp;<a href="http://blog.apollographql.com/" target="_blank" rel="noreferrer noopener">Apollo blog</a>.</p>



<h2 class="wp-block-heading" id="b57d"><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>



<p>Submit your idea using our 👉&nbsp;<a href="https://docs.google.com/forms/d/e/1FAIpQLSdlnoe3luY7qK4Q6PUZSAke9lRpVRgMjrkcO2jZpwfy-9KSDQ/viewform" target="_blank" rel="noreferrer noopener">Blog Post Proposal Form</a>!</p>



<p>Don’t worry, your first draft doesn’t have to be perfect! We’ll work with you to transform it into an awesome blog post.</p>



<p>If you’ve already written something that you think would be useful for the Apollo developer community, feel free to submit that as well.</p>



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



<p>Here are a few examples of the types of blog posts we’d love to read.</p>



<ul class="wp-block-list"><li>“How to” guides, recipes, or tutorials on how to address problems you’ve solved with Apollo (here’s an example, “<a target="_blank" rel="noreferrer noopener" href="https://blog.apollographql.com/apollo-client-react-how-to-query-on-click-c1d4fecf9b66">Apollo Client [React] — How to Query on Click</a>”)</li><li>Stories about how Apollo helped you overcome different challenges on work and personal projects</li><li>Something cool you built with Apollo</li><li>Showcasing a tool, fix, or other content you or someone else has contributed to Apollo’s open source community</li><li>Guidance and resources for learning Apollo, GraphQL, best practices, architecture, different tools/integrations, and other Apollo-related content.</li><li>Any other topics that you think would be valuable to people learning about or working with Apollo</li></ul>



<p>We’re open to all kinds of topics as long as it relates to Apollo in some way. We love posts of all reading levels (beginner to intermediate, to advanced). If you’re stumped, we especially like posts that mix Apollo with the following topics:</p>



<ul class="wp-block-list"><li>TypeScript</li><li>GraphQL best practices</li><li>Caching</li><li>React.js</li><li>Authentication &amp; authorization</li><li>Error handling</li><li>Front-end development</li><li>Server-side development</li><li>Scaling GraphQL</li><li>Schema design</li></ul>



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



<p>For more information on the process and the content we’d love to read, check out our <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/community/blog-post-contributions/" target="_blank">Blog Post Submission docs</a>.</p>



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



<p>We can’t wait to see what you’ve been working on and the problems you’ve been solving!</p>



<p>👉<a href="https://docs.google.com/forms/u/2/d/e/1FAIpQLSdlnoe3luY7qK4Q6PUZSAke9lRpVRgMjrkcO2jZpwfy-9KSDQ/viewform" target="_blank" rel="noreferrer noopener">Submit your idea here</a>!</p>


How to Contribute to the Apollo Developer Blog

☝️ GraphQL File Uploads with Apollo Server 2, React Hooks, TypeScript & Amazon S3 [Tutorial]


<p>Modern apps are chatty—they require a lot of data, and thus make a lot of requests to underlying services to fulfill those needs. Layering GraphQL over your services solves this issue, since it encapsulates multiple requests into a single operation, avoiding the cost of multiple round trips.</p>



<p>While GraphQL encourages this style of data fetching, React encourages developers to split up data fetching logic to be colocated with the components that use it. This pattern is extremely useful, but can lead to many of the same issues of an app making too many network requests for a server to handle at scale. The idea of batching client operations can be applied to GraphQL clients to solve many of these issues, but sometimes batching can hurt more than help.</p>



<p>To batch, or not to batch, that is the question.</p>



<p>By the end of this post, you should be able to answer the following questions about batching client operations with Apollo:</p>



<ul class="wp-block-list"><li>How does batching work?</li><li>What are the tradeoffs with batching?</li><li>Is batching necessary?</li><li>Can batching be done manually?</li><li>Can I fix automatic batching?</li></ul>



<h2 class="wp-block-heading" id="5853"><a href="#how-does-batching-work" aria-hidden="true" class="aal_anchor" id="how-does-batching-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 does batching work?</h2>



<p>Batching is the process of taking a group of requests, combining them into one, and making a single request with the same data that all of the other queries would have made. This is usually done with a timing threshold. For example, with a threshold of 50ms, if a query is made from a component, instead of making the query immediately, the client waits 50ms. If any other queries are requested in that 50ms, all of those additional queries are requested at the same time, rather than separately.</p>



<p>In GraphQL apps, batching usually takes one of two forms. The first form takes all operations and combines them into a single operation using the alias feature in GraphQL. This approach is not recommended, however, since this removes the ease of tracking metrics on a per-operation basis and adds additional complexity to the client.</p>



<p>Instead, we recommend sending an array of operations to a GraphQL server, having the server recognize the request as an array of operations instead of a single one, and handle each operation separately. This method still requires only a single round-trip, while retaining the ability to track single operation performance. Apollo Client handles batching like this using&nbsp;<code>apollo-link-batch-http</code>. It’s also worth noting that this method requires the server to be able to receive an array of operations as well as single operations. Luckily,&nbsp;<code>apollo-server</code>&nbsp;supports this out of the box.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="546" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-1024x546.png" alt="" class="wp-image-678" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-1024x546.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-300x160.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-768x410.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-1200x640.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA.png 1500w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>How Apollo batches operations with an array</figcaption></figure>



<p>For a deeper dive into how batching works with Apollo, check out&nbsp;<a target="_blank" rel="noreferrer noopener" href="https://blog.apollographql.com/query-batching-in-apollo-63acfd859862">this post</a>&nbsp;introducing batching in an earlier version of Apollo Client. Even though some of the implementation details have changed, the concepts are still relevant today.</p>



<h2 class="wp-block-heading" id="a63a"><a href="#what-are-the-tradeoffs-with-batching" aria-hidden="true" class="aal_anchor" id="what-are-the-tradeoffs-with-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>What are the tradeoffs with batching?</h2>



<p>Batching may sound like the perfect solution to some network performance issues on the client, but it’s far from perfect. Request batching is prone to slow loading times on the client. For example, if five requests from separate components are made to the GraphQL endpoint, and one of the five requests take a long time, the client won’t get&nbsp;<em>any</em>&nbsp;of the results back until&nbsp;<em>all</em>&nbsp;operations have been resolved. In other words, batched operations are always as slow as the slowest operation in the batch.</p>



<p>Since GraphQL is often used to aggregate data from multiple data sources, this can be problematic. If one of the underlying services is slower than the rest, the effects may be felt across the whole client app.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="400" height="227" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1__1VoQ49cbUEPHL7RPsl0og.gif" alt="" class="wp-image-677"/></figure>



<p>Additionally, batching makes it much harder to debug network traffic. In most scenarios, if a specific operation was taking a long time to resolve, it would be obvious. The component making the query would be stuck in a loading state, and the rest of the app would function normally. Additionally, when using browser debugging tools, slow network requests can usually be found easily. Batching queries makes both of these debugging methods more difficult.</p>



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



<p>Before looking at solutions to the issues that batching introduces, it’s important to question whether batching is even needed in the first place. Since enabling batching is as easy as replacing one&nbsp;<code>apollo-link</code>&nbsp;with another, it&#8217;s tempting to introduce batching at the onset of a project, without any real evidence that batching is needed. In fact, because of its drawbacks, we don’t recommend batching unless performance issues are still present after all of the following steps have been taken:</p>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/guides/performance.html#automatic-persisted-queries" target="_blank" rel="noreferrer noopener">Use automatic persisted queries</a>&nbsp;(APQ) to reduce the request body size.</li><li><a href="https://www.apollographql.com/docs/guides/performance.html#get" target="_blank" rel="noreferrer noopener">Cache requests with a CDN</a>&nbsp;to prevent operations from ever reaching the GraphQL endpoint.</li><li>Enable partial query caching with&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/features/data-sources.html" target="_blank" rel="noreferrer noopener">Apollo Server</a>&nbsp;to make operation resolution significantly quicker in most cases.</li><li>If possible, use HTTP/2 on the server (with Node.js 10), which allows multiplexing of requests, effectively batching them.</li></ul>



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



<p>Yes! Batching can be done manually. Often, for the cases where batching may still be a necessity, inexpensive operations can be manually batched together to prevent unnecessary requests. In GraphQL, this is done by combining smaller queries into one larger one. For example, if there was a page with four content blocks on it, rather than having each block fetch its own data, a&nbsp;<code>container</code>&nbsp;could fetch the data and pass it to the components manually. This is conceptually similar to the first implementation of batching described in the first section.</p>



<p>This may sound counterintuitive to the patterns that have been established, like colocating queries with the components that use their response, but there are ways around this.</p>



<p>This isn’t suggesting to write one large GraphQL query at the container-level. Instead, write queries normally, next to the components that use them. When you’re ready to optimize a section of an app, convert those queries to&nbsp;<a href="https://www.apollographql.com/docs/react/advanced/fragments.html" target="_blank" rel="noreferrer noopener">fragments</a>&nbsp;and export them from the component file. You can then import these fragments in the container, let the container make the single, large query, and pass the fragment results back to the children. Using container components in this way can even allow you to control loading and error states at the container-level, rather than in each component.</p>



<p>Take a look at this CodeSandbox for a full example of this in action:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Manual Query Batching" width="580" height="870" src="https://codesandbox.io/embed/wnyxmy8kv7#?secret=5eT4FyMOe1" data-secret="5eT4FyMOe1"></iframe>
</div></figure>



<p>Even manual batching has issues, though. Since manually batched operations are much larger,&nbsp;<strong>their ability to take advantage of whole-query caching is reduced</strong>. Whole-query cache TTLs are based on the field in an operation with the shortest TTL. Increasing the number of fields in an operation increases the chances that a field that can’t be cached for a long time is included, reducing the ability to cache the whole operation. For more on whole-query caching, and how these TTLs are calculated,&nbsp;<a href="https://www.apollographql.com/docs/engine/proxy/guides.html#cache-hints" target="_blank" rel="noreferrer noopener">read this doc</a>.</p>



<h2 class="wp-block-heading" id="dae7"><a href="#can-i-fix-automatic-batching" aria-hidden="true" class="aal_anchor" id="can-i-fix-automatic-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>Can I fix automatic batching?</h2>



<p>There is no silver bullet for batching. If batching is enabled, there is always the potential for portions of the batch to run slower, and thus hold up the remaining portions of the batch. Sometimes, however, the trouble of manually batching operations outweighs the benefits. Manually batching may be too complicated, or too large of a refactor to reasonably undertake.</p>



<p>Some of the issues around batching can be solved by manually&nbsp;<em>debatching</em>&nbsp;expensive operations–that is, allowing most operations to be batched like normal, but preventing batching for ones that are known to cause issues. Doing this requires a few steps:</p>



<ol class="wp-block-list"><li>Build components as usual, with colocated queries.</li><li>Identify the most expensive operations using a tool like&nbsp;<a href="https://www.apollographql.com/engine" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;(these are not necessarily just the largest queries).</li><li>Mark expensive operations on the client using an operation’s&nbsp;<code>context</code>. You can set the context by specifying a prop on your&nbsp;<code>Query</code>&nbsp;component.</li><li>Use&nbsp;<code>&lt;a href=&quot;https://www.apollographql.com/docs/link/composition.html#directional&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;split&lt;/a&gt;</code>&nbsp;to switch between&nbsp;<code>apollo-link-http</code>&nbsp;or&nbsp;<code>apollo-link-batch-http</code>&nbsp;depending on the context of the operation.</li></ol>



<p>Take a look at this CodeSandbox for a full example of this in action:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Link switching for batches (blog)" width="580" height="870" src="https://codesandbox.io/embed/14xk74wk0q#?secret=S2SdbHI0bf" data-secret="S2SdbHI0bf"></iframe>
</div></figure>



<h2 class="wp-block-heading" id="a1d1"><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>Batching is a tricky topic. There are plenty of reasons to use some form of client request batching, but many times these solutions just cause more problems than they solve.</p>



<p>Hopefully, armed with this information, you can feel confident when making a decision about how to boost performance on the client.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="480" height="359" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_z1jNMuLYJ-eOi_TGIjkjNw.gif" alt="" class="wp-image-676"/></figure>



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


Batching Client GraphQL Queries

Deploy a fullstack Apollo app with Netlify


<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>GraphQL is a powerful and flexible way to expose data to client applications. It empowers application teams to describe the exact data they need for each feature without having to coordinate with a backend team. That flexiblity dramatically reduces the amount of code teams need to write and accelerates how quickly they can ship applications.</p>



<p>But with that flexibility comes a need for management and control. Teams growing their use GraphQL constantly make changes to their schema by adding data, refactoring types, retiring unused or deprecated fields and more. To be able to do that safely, it’s essential to know which parts of the schema are used by each client, and to understand the impact of a schema change on your application. So how does a fast moving team evolve their schema?</p>



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



<p>Starting today teams using Apollo Engine can validate their schema against previous versions and against&nbsp;<strong>real world usage</strong>&nbsp;of their API. This incredible new workflow lets teams of any size manage and validate changes to their API while taking advantage of GraphQL’s flexibility to allow each client to fetch exactly the data it needs.</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="534" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1-1024x534.png" alt="" class="wp-image-733" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1-1024x534.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1-300x156.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1-768x400.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1-1536x801.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1-1200x626.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_0WTDjPgNtvD83zqGTJEaIg-1.png 1707w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>To learn more about how Engine empowers teams keep reading, but if you want to give it a try right now head over to the&nbsp;<a href="https://www.apollographql.com/docs/engine/schema-history.html" target="_blank" rel="noreferrer noopener">docs&nbsp;</a>and&nbsp;<em>publish away</em>!</p>



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



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="715" height="906" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_goysdOpO-FyhnkudMxpQDQ-1.png" alt="" class="wp-image-730" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_goysdOpO-FyhnkudMxpQDQ-1.png 715w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_goysdOpO-FyhnkudMxpQDQ-1-237x300.png 237w" sizes="(max-width: 715px) 100vw, 715px" /></figure>



<p>A lot can change between two versions of a GraphQL schema. Changes to types, fields, directives and more can be dangerous to shipped client applications. So how can a team know what is safe to change and what will trigger a PagerDuty alert at 3 am? Even graphql-js includes a couple undocumented utilities to find&nbsp;<a href="https://github.com/graphql/graphql-js/blob/master/src/utilities/findBreakingChanges.js" target="_blank" rel="noreferrer noopener">breaking and dangerous changes</a>&nbsp;but these are only a part of the picture needed to evolve your schema.</p>



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



<p>The most important tool to evolving a schema safely is to know how it is being&nbsp;<strong>used</strong>. Changing a return type could have no impact at all if that field was only used in a really old version of the app. Apollo Engine will use historical data on operations used by clients as far back as 90 days to determine if schema changes would break any operations being sent. It does this by replaying all observed operations against a diff of the two schemas and finding usage patterns that would lead to broken apps.</p>



<p>Instead of being held hostage by past decisions, with Apollo Engine teams can have full confidence in how they change their schema.</p>



<p>Replaying fine grained usage data opens the door to a new kind of API governance that doesn’t exist in the REST ecosystem. Using Apollo provides the most accurate and granular information to make smart decisions about changing your services. Static analysis is just not enough to correctly identify critical parts of your schema, but instead the rich data Engine provides, combined with other Apollo tooling, makes GraphQL the perfect way to manage data in your application.</p>



<h2 class="wp-block-heading" id="5690"><a href="#track-changes-over-time" aria-hidden="true" class="aal_anchor" id="track-changes-over-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>Track changes over time</h2>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="690" height="208" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_MccyANW-o8TSsn2c0866uA-1.png" alt="" class="wp-image-728" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_MccyANW-o8TSsn2c0866uA-1.png 690w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MccyANW-o8TSsn2c0866uA-1-300x90.png 300w" sizes="(max-width: 690px) 100vw, 690px" /></figure>



<p>Products change over time, and with safely evolving schemas, GraphQL endpoints can seamlessly evolve into the right shape of data the product needs. Much like a git history, having a historical timeline of how these changes can really improve a team’s response rate to issues, fosters communication between backend and frontend teams, and aides in the reviewing of changes. With Apollo Engine, teams can now publish every change of their schema and track the exact commit that caused a change.</p>



<h2 class="wp-block-heading" id="e85a"><a href="#supercharge-your-workflow" aria-hidden="true" class="aal_anchor" id="supercharge-your-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>Supercharge your workflow</h2>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="455" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Iie3p1Ho_NMdGepFdKTisQ-1024x455.gif" alt="" class="wp-image-729" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Iie3p1Ho_NMdGepFdKTisQ-1024x455.gif 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Iie3p1Ho_NMdGepFdKTisQ-300x133.gif 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Iie3p1Ho_NMdGepFdKTisQ-768x341.gif 768w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>With all that can change between two versions of a schema, it is really difficult to effectively review pull requests that introduce changes. To add to the complexity, teams that own the GraphQL server aren’t always the ones actually&nbsp;<strong>using&nbsp;</strong>it! What seems like a small backend tweak could break production apps without anyone knowing what happened. That is why Apollo Engine works with the most critical part of teams workflow, the GitHub pull request.</p>



<p>Last month, GitHub introduced their new&nbsp;<a href="https://blog.github.com/2018-05-07-introducing-checks-api/" target="_blank" rel="noreferrer noopener">checks platform</a>&nbsp;to improve the code review process for teams. I am so excited that we are launching full checks API integration today for schema validation. Here is how it works:</p>



<ol class="wp-block-list"><li>Configure the&nbsp;<a href="https://github.com/apps/apollo-engine" target="_blank" rel="noreferrer noopener">Apollo Engine GitHub app</a></li><li>Run&nbsp;<code>apollo schema:check</code>&nbsp;on every commit</li><li>View the difference in GitHub!</li></ol>



<p>Engine will update the status of a pull request to prevent breaking changes from going into production and comment back detailed information about what changed.&nbsp;<strong>Think of it like a CI for GraphQL!</strong></p>



<p>You can see this in action on our example project&nbsp;<a href="https://github.com/apollographql/GitHunt-API/pull/280/checks?check_run_id=4703076" target="_blank" rel="noreferrer noopener">GitHunt</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="629" height="1024" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-629x1024.png" alt="" class="wp-image-731" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-629x1024.png 629w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-184x300.png 184w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-768x1250.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-944x1536.png 944w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-1258x2048.png 1258w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q-1200x1953.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_x8sKiI0KH-iC78Ca2Qbf-Q.png 1683w" sizes="(max-width: 629px) 100vw, 629px" /></figure>



<h2 class="wp-block-heading" id="6945"><a href="#get-started-today" aria-hidden="true" class="aal_anchor" id="get-started-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>Get started today</h2>



<p>As long as I’ve been working on GraphQL for production applications, I’ve wanted a safe way to change my schema. Schema design can be scary, and at Apollo we are committed to making it easier through&nbsp;<a href="https://www.apollographql.com/docs/guides/schema-design.html" target="_blank" rel="noreferrer noopener">in-depth guides</a>,&nbsp;<a href="https://www.apollographql.com/support" target="_blank" rel="noreferrer noopener">workshops and support</a>, and powerful tools like Engine. To try out this feature today, head over to our&nbsp;<a href="https://www.apollographql.com/docs/engine/schema-history.html" target="_blank" rel="noreferrer noopener">docs</a>&nbsp;and publish away!</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="550" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_2uBo_72nNflD7JIoi9QpsA-1024x550.gif" alt="" class="wp-image-732" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_2uBo_72nNflD7JIoi9QpsA-1024x550.gif 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_2uBo_72nNflD7JIoi9QpsA-300x161.gif 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_2uBo_72nNflD7JIoi9QpsA-768x412.gif 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_2uBo_72nNflD7JIoi9QpsA-1536x825.gif 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_2uBo_72nNflD7JIoi9QpsA-1200x644.gif 1200w" sizes="(max-width: 1024px) 100vw, 1024px" /></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>


Schema Validation with Apollo Engine


<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="(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="(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="(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="(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>We’ve been working on a new&nbsp;<a href="https://www.apollographql.com/docs">guides and best practices site</a>&nbsp;for Apollo and GraphQL that covers some of the most important topics we’ve heard from our users. This post reproduces part of the&nbsp;<a rel="noreferrer noopener" href="https://www.apollographql.com/docs/react/recipes/testing" target="_blank">Testing React Components</a>&nbsp;article, and if you’d like to read more about testing (including mutation components), and other best practices, check out the&nbsp;<a href="https://www.apollographql.com/docs/guides/testing-react-components.html">full article</a>&nbsp;on the site!</p>



<p>As always, we’re grateful to the community help that makes Apollo possible. Thanks to&nbsp;<a href="https://medium.com/u/b016d103ae51?source=post_page-----d575dc642e04----------------------" target="_blank" rel="noreferrer noopener">Dirk-Jan Rutten</a>&nbsp;for&nbsp;<a href="https://github.com/apollographql/apollo-client/pull/3309" target="_blank" rel="noreferrer noopener">kick-starting this article on GitHub</a>!</p>



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



<p>Running tests against your code has long been a best practice. Testing provides additional security for the code that’s already written, and prevents accidental regressions in the future. Components utilizing&nbsp;<code>react-apollo</code>, the React integration for Apollo Client, are no exception.</p>



<p>Although&nbsp;<code>react-apollo</code>&nbsp;has a lot going on under the hood to make your life as a React developer easy, the library provides multiple tools for testing that simplify those abstractions, and allows complete focus on the component logic. These testing utilities have long been used to test the&nbsp;<code>react-apollo</code>&nbsp;library itself, and they will be supported long-term.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="513" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-1024x513.png" alt="" class="wp-image-740" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-1024x513.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-768x385.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-1536x769.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-2048x1026.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-1200x601.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_EopQgfU7303F3YpVFwi7uA-1980x992.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The goal: Lots of green checkmarks!</figcaption></figure>



<h2 class="wp-block-heading" id="9865"><a href="#testing-against-remote-data" aria-hidden="true" class="aal_anchor" id="testing-against-remote-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>Testing against remote data</h2>



<p>The&nbsp;<code>react-apollo</code>&nbsp;libary relies on&nbsp;<a href="https://reactjs.org/docs/context.html" target="_blank" rel="noreferrer noopener">context</a>&nbsp;in order to pass the&nbsp;<code>ApolloClient</code>&nbsp;instance through the React component tree. In addition,&nbsp;<code>react-apollo</code>&nbsp;makes network requests in order to fetch data. This behavior affects how tests should be written for components that use&nbsp;<code>react-apollo</code>.</p>



<p>This guide will explain step-by-step how to test&nbsp;<code>react-apollo</code>&nbsp;code. The following examples use the&nbsp;<a href="https://facebook.github.io/jest/docs/en/tutorial-react.html" target="_blank" rel="noreferrer noopener">Jest</a>&nbsp;testing framework, but most concepts should be reusable with other libraries. These examples aim to use as simple of a toolset as possible, so React’s&nbsp;<a href="https://reactjs.org/docs/test-renderer.html" target="_blank" rel="noreferrer noopener">test renderer</a>&nbsp;will be used in place of React-specific tools like&nbsp;<a href="https://github.com/airbnb/enzyme" target="_blank" rel="noreferrer noopener">Enzyme</a>&nbsp;and&nbsp;<a href="https://github.com/kentcdodds/react-testing-library" target="_blank" rel="noreferrer noopener">react-testing-library</a>.</p>



<p>Consider the component below, which makes a basic query, and displays its results:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">import React from &#039;react&#039;;
import gql from &#039;graphql-tag&#039;;
import { Query } from &#039;react-apollo&#039;;

// Make sure the query is also exported -- not just the component
export const GET_DOG_QUERY = gql`
  query getDog($name: String) {
    dog(name: $name) {
      id
      name
      breed
    }
  }
`;

export const Dog = ({ name }) =&gt; (
  &lt;Query query={GET_DOG_QUERY} variables={{ name }}&gt;
    {({ loading, error, data }) =&gt; {
      if (loading) return &#039;Loading...&#039;;
      if (error) return `Error!`;

      return (
        &lt;p&gt;
          {data.dog.name} is a {data.dog.breed}
        &lt;/p&gt;
      );
    }}
  &lt;/Query&gt;
);</code></pre>



<p>Given this component, let’s try to render it inside a test, just to make sure there are no render errors:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// Broken because it&#039;s missing Apollo Client in the context
it(&#039;should render without error&#039;, () =&gt; {
  renderer.create(&lt;Dog name=&quot;Buck&quot; /&gt;);
});</code></pre>



<p>This test would produce an error because Apollo Client isn’t available on the context for the&nbsp;<code>Query</code>&nbsp;component to consume.</p>



<p>In order to fix this we could wrap the component in an&nbsp;<code>ApolloProvider</code>&nbsp;and pass an instance of Apollo Client to the&nbsp;<code>client</code>&nbsp;prop:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">// Not predictable
it(&#039;renders without error&#039;, () =&gt; {
  renderer.create(
    &lt;ApolloProvider client={client}&gt;
      &lt;Dog name=&quot;Buck&quot; /&gt;
    &lt;/ApolloProvider&gt;,
  );
});</code></pre>



<p>However, this will cause the tests to run against an actual backend which makes the tests very unpredictable for the following reasons:</p>



<ul class="wp-block-list"><li>The server could be down.</li><li>There may be no network connection.</li><li>The results are not guaranteed to be the same for every query.</li></ul>



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



<p>The&nbsp;<code>react-apollo/test-utils</code>&nbsp;module exports a&nbsp;<code>MockedProvider</code>&nbsp;component which simplifies the testing of React components by mocking calls to the GraphQL endpoint. This allows the tests to be run in isolation and provides consistent results on every run by removing the dependence on remote data.</p>



<p>By using this&nbsp;<code>MockedProvider</code>&nbsp;component, it’s possible to specify the exact results that should be returned for a certain query using the&nbsp;<code>mocks</code>&nbsp;prop.</p>



<p>Here’s an example of a test for the above&nbsp;<code>Dog</code>&nbsp;component using&nbsp;<code>MockedProvider</code>, which shows how to define the mocked response for&nbsp;<code>GET_DOG_QUERY</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">// dog.test.js

import { MockedProvider } from &#039;react-apollo/test-utils&#039;;

// The component AND the query need to be exported
import { GET_DOG_QUERY, Dog } from &#039;./dog&#039;;

const mocks = [
  {
    request: {
      query: GET_DOG_QUERY,
      variables: {
        name: &#039;Buck&#039;,
      },
    },
    result: {
      data: {
        dog: { id: &#039;1&#039;, name: &#039;Buck&#039;, breed: &#039;bulldog&#039; },
      },
    },
  },
];

it(&#039;renders without error&#039;, () =&gt; {
  renderer.create(
    &lt;MockedProvider mocks={mocks} addTypename={false}&gt;
      &lt;Dog name=&quot;Buck&quot; /&gt;
    &lt;/MockedProvider&gt;,
  );
});</code></pre>



<p>The&nbsp;<code>mocks</code>&nbsp;array takes objects with specific&nbsp;<code>request</code>s and their associated&nbsp;<code>result</code>s. When the provider receives a&nbsp;<code>GET_DOG_QUERY</code>&nbsp;with matching&nbsp;<code>variables</code>, it returns the corresponding object from the&nbsp;<code>result</code>&nbsp;key.</p>



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



<p>You may notice the prop being passed to the&nbsp;<code>MockedProvider</code>&nbsp;called&nbsp;<code>addTypename</code>. The reason this is here is because of how Apollo Client normally works. When a request is made with Apollo Client normally, it adds a&nbsp;<code>__typename</code>&nbsp;field to every object type requested. This is to make sure that Apollo Client’s cache knows how to normalize and store the response. When we’re making our mocks, though, we’re importing the raw queries&nbsp;<em>without typenames</em>&nbsp;from the component files.</p>



<p>If we don’t disable the adding of typenames to queries, the imported query won’t match the query actually being run by the component during our tests.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><em>In short, if queries are lacking&nbsp;</em><code>&lt;em&gt;__typename&lt;/em&gt;</code><em>, it’s important to pass the&nbsp;</em><code>&lt;em&gt;addTypename={false}&lt;/em&gt;</code><em>&nbsp;prop to the&nbsp;</em><code>&lt;em&gt;MockedProvider&lt;/em&gt;</code><em>.</em></p></blockquote>



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



<p>In this example, the&nbsp;<code>Dog</code>&nbsp;component will render, but it will render in a loading state, not the final response state. This is because&nbsp;<code>MockedProvider</code>&nbsp;doesn’t just return the data but instead returns a&nbsp;<code>Promise</code>&nbsp;that will resolve to that data. By using a&nbsp;<code>Promise</code>&nbsp;it enables testing of the loading state in addition to the final state:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">it(&#039;should render loading state initially&#039;, () =&gt; {
  const component = renderer.create(
    &lt;MockedProvider mocks={[]}&gt;
      &lt;Dog /&gt;
    &lt;/MockedProvider&gt;,
  );

  const tree = component.toJSON();
  expect(tree.children).toContain(&#039;Loading...&#039;);
});</code></pre>



<p>This shows a basic example test that tests the loading state of a component by checking that the children of the component contain the text&nbsp;<code>Loading...</code>. In an actual application, this test would probably be more complicated, but the testing logic would be the same.</p>



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



<p>Loading state, while important, isn’t the only thing to test. To test the final state of the component after receiving data, we can just wait for it to update and test the final state.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">const wait = require(&#039;waait&#039;);

it(&#039;should render dog&#039;, async () =&gt; {
  const dogMock = {
    request: {
      query: GET_DOG_QUERY,
      variables: { name: &#039;Buck&#039; },
    },
    result: {
      data: { dog: { id: 1, name: &#039;Buck&#039;, breed: &#039;poodle&#039; } },
    },
  };

  const component = renderer.create(
    &lt;MockedProvider mocks={[dogMock]} addTypename={false}&gt;
      &lt;Dog name=&quot;Buck&quot; /&gt;
    &lt;/MockedProvider&gt;,
  );

  await wait(0); // wait for response

  const p = component.root.findByType(&#039;p&#039;);
  expect(p.children).toContain(&#039;Buck is a poodle&#039;);
});</code></pre>



<p>Here, you can see the&nbsp;<code>await wait(0)</code>&nbsp;line. This is a utility function from the&nbsp;<code>&lt;a href=&quot;https://npm.im/waait&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;waait&lt;/a&gt;</code>&nbsp;npm package. It delays until the next “tick” of the event loop, and allows time for that&nbsp;<code>Promise</code>&nbsp;returned from&nbsp;<code>MockedProvider</code>&nbsp;to be fulfilled. After that&nbsp;<code>Promise</code>&nbsp;resolves (or rejects), the component can be checked to ensure it displays the correct information — in this case, “Buck is a poodle”.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="500" height="244" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_jgFr1nhOITWQphBedPE34A.gif" alt="" class="wp-image-741"/><figcaption>✅ is a great feeling</figcaption></figure>



<p>For more complex UI with heavy calculations, or delays added into its render logic, the&nbsp;<code>wait(0)</code>&nbsp;will not be long enough. In these cases, you could either increase the wait time or use a package like&nbsp;<code>&lt;a href=&quot;https://npm.im/wait-for-expect&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;wait-for-expect&lt;/a&gt;</code>&nbsp;to delay until the render has happened. The risk of using a package like this everywhere by default is that&nbsp;<em>every&nbsp;</em>test could take up to five seconds to execute (or longer if the default timeout has been increased).</p>



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



<p>Since they can make or break the experience a user has when interacting with the app, error states are one of the most important states to test, but are often less tested in development.</p>



<p>Since most developers would follow the “happy path” and not encounter these states as often, it’s almost&nbsp;<em>more</em>important to test these states to prevent accidental regressions.</p>



<p>To simulate a GraphQL error, an&nbsp;<code>error</code>&nbsp;property can be included on the mock, in place of or in addition to the&nbsp;<code>result</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">it(&#039;should show error UI&#039;, async () =&gt; {
  const dogMock = {
    request: {
      query: GET_DOG_QUERY,
      variables: { name: &#039;Buck&#039; },
    },
    error: new Error(&#039;aw shucks&#039;),
  };

  const component = renderer.create(
    &lt;MockedProvider mocks={[dogMock]} addTypename={false}&gt;
      &lt;Dog name=&quot;Buck&quot; /&gt;
    &lt;/MockedProvider&gt;,
  );

  await wait(0); // wait for response

  const tree = component.toJSON();
  expect(tree.children).toContain(&#039;Error!&#039;);
});</code></pre>



<p>Here, whenever the&nbsp;<code>MockedProvider</code>&nbsp;receives a&nbsp;<code>GET_DOG_QUERY</code>&nbsp;with matching&nbsp;<code>variables</code>, it will return the error assigned to the&nbsp;<code>error</code>&nbsp;property in the mock. This forces the component into the error state, allowing verification that it’s being handled gracefully.</p>



<p>Testing UI components isn’t a simple issue, but hopefully these tools will create confidence when testing components that are dependent on data.</p>



<p>For a working example, check out&nbsp;<a href="https://codesandbox.io/s/40k7j708n4" target="_blank" rel="noreferrer noopener">this CodeSandbox</a>.</p>



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



<h3 class="wp-block-heading" id="16ed"><a href="#read-more-in-the-full-guide" aria-hidden="true" class="aal_anchor" id="read-more-in-the-full-guide"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 more in the full guide!</h3>



<p>For more, including how to test <code>Mutation</code> components, check out the <a href="https://www.apollographql.com/docs/guides/testing-react-components.html">Testing React Components</a> page on <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/" target="_blank">our new guides and best practices site</a>!</p>


Testing Apollo’s Query Component


<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="(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="(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="(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="(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


<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="(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>The best thing about GraphQL as an API technology is that it’s focused on the needs of product developers. You simply describe the data you want for a particular part of your UI with a query, and the GraphQL server takes care of assembling it for you. And because all modern GraphQL clients follow the practice of sending&nbsp;<a href="https://dev-blog.apollodata.com/5-benefits-of-static-graphql-queries-b7fa90b0b69a" target="_blank" rel="noreferrer noopener">static, predictable queries</a>, you can easily associate the queries that hit your API with the parts of the UI that are using those results.</p>



<p>For example, if you see a query called&nbsp;<code>ServicesListQuery</code>&nbsp;hit your API, you can tell that this data is going to be used for the&nbsp;<code>ServicesList</code>&nbsp;component in the frontend. This is a huge benefit of GraphQL over a more “generic” API, where a&nbsp;<code>/services</code>&nbsp;endpoint might be used by dozens of components in different ways.</p>



<p>To take advantage of this, you need a monitoring and reporting tool that natively understands GraphQL and can show you details on the level of individual queries and resolvers. That’s where&nbsp;<a href="https://www.apollographql.com/engine/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;comes in.</p>



<h3 class="wp-block-heading" id="850a"><a href="#announcing-daily-slack-reports-and-api-overview" aria-hidden="true" class="aal_anchor" id="announcing-daily-slack-reports-and-api-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>Announcing: Daily Slack reports and API overview</h3>



<p>Starting today, Engine can send you a bird’s-eye view of your GraphQL API, with a breakdown of your most important queries, both in the dashboard and in a compact daily Slack report.</p>



<p>Here’s what it looks like:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="926" height="1024" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_MZXdBZeH5M7jU_dTbMYV2A-926x1024.png" alt="" class="wp-image-812" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_MZXdBZeH5M7jU_dTbMYV2A-926x1024.png 926w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MZXdBZeH5M7jU_dTbMYV2A-271x300.png 271w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MZXdBZeH5M7jU_dTbMYV2A-768x849.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_MZXdBZeH5M7jU_dTbMYV2A.png 1174w" sizes="(max-width: 926px) 100vw, 926px" /></figure>



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



<p>If you haven’t set up Engine in your GraphQL server yet, here’s how:</p>



<ol class="wp-block-list"><li><a href="https://www.apollographql.com/docs/engine/setup-node.html" target="_blank" rel="noreferrer noopener">Add Engine to your Node.js API in about 5 minutes</a></li><li><a href="https://www.apollographql.com/docs/engine/setup-standalone.html" target="_blank" rel="noreferrer noopener">Use Engine with any GraphQL API with Docker</a></li></ol>



<p>Now, let’s dive in to how these new features work.</p>



<h2 class="wp-block-heading" id="77b6"><a href="#new-service-overviews-and-reports-in-engine" aria-hidden="true" class="aal_anchor" id="new-service-overviews-and-reports-in-engine"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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: Service overviews and reports in Engine</h2>



<p>Engine has always enabled you to see how your GraphQL API is working, down to the level of individual queries, mutations, and resolvers. Starting today, Engine will also provide you reports that show you what parts of your API need your attention.</p>



<p>When you log into your Engine dashboard today, you’ll immediately see an overview of your most interesting GraphQL operations:</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="481" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-1024x481.png" alt="" class="wp-image-813" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-1024x481.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-300x141.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-768x361.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-1536x721.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-1200x564.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg-1980x930.png 1980w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Jsr778q0ffRMVXyPPlDvrg.png 2014w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>Visit your&nbsp;<a href="https://engine.apollographql.com/" target="_blank" rel="noreferrer noopener">Engine dashboard</a>&nbsp;to see this new view!</figcaption></figure>



<p>And, so that you don’t need to log into Engine every day to keep an eye on what’s going on, you can get the same information delivered in a daily report to the Slack channel of your choice.</p>



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



<p>We’ve been testing this feature with some early-access customers to make sure that the data presented is the most relevant information you would want to know about your API. Here’s how you can use it to identify issues:</p>



<ol class="wp-block-list"><li><strong>Request rate:&nbsp;</strong>The number of operations per minute, and a list of the most popular operations. A dip in this metric might mean some frontends aren’t able to reach your server!</li><li><strong>p95 service time:&nbsp;</strong>The time under which 95% of operations are executing, and a great representation of the majority user experience. Consistent slowness could indicate an overloaded API, and the operation details will show the worst offenders.</li><li><strong>Error percentage:&nbsp;</strong>Spikes in error percentages may indicate malfunctions in your backend, and knowing which operations are most error-prone will help find precisely where to look.</li></ol>



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



<p>Once you identify something that needs extra attention, you can click on any of the listed operations to get a more detailed view. This will help you find extra information that you can use to address the issue, taking you directly to a detailed trace of the operation timing or a specific error message:</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="338" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw-1024x338.png" alt="" class="wp-image-814" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw-1024x338.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw-300x99.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw-768x254.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw-1536x508.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw-1200x397.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FNp6lKrH912NAv5RDbFdMw.png 1915w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The detailed trace view that tells you timing for each field in your operation.</figcaption></figure>



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



<p>Turning on reports for your GraphQL API is really simple. First, click on the “Daily Reports” button in the top right of the Engine UI:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="136" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-1024x136.png" alt="" class="wp-image-815" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-1024x136.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-300x40.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-768x102.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-1536x204.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-2048x272.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-1200x159.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ATice45F4divxzfC-L9jNQ-1980x263.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>You’ll see a form that will allow you to set up a new Slack channel:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="808" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-1024x808.png" alt="" class="wp-image-816" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-1024x808.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-300x237.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-768x606.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-1536x1212.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-2048x1616.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-1200x947.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_DaiQYZfWABovahxlGoaqIQ-1980x1562.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Follow the directions in the popup to add a Webhook URL to one of your channels, and then paste that URL into Engine. You’ll get a confirmation message in the channel you picked, like so:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="164" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_RmAAxmmX2wqPetFD3OQGOw-1024x164.png" alt="" class="wp-image-817" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_RmAAxmmX2wqPetFD3OQGOw-1024x164.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RmAAxmmX2wqPetFD3OQGOw-300x48.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RmAAxmmX2wqPetFD3OQGOw-768x123.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RmAAxmmX2wqPetFD3OQGOw.png 1152w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Now you’re good to go! In a short while, you’ll see daily reports from Engine show up in your channel.</p>



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



<p>There are all kinds of API monitoring and reporting tools out there, but this type of report demonstrates why having something built around GraphQL makes a big difference. When you see GraphQL queries from your UI show up in the daily report, you not only get a sense of how your API is operating, but you can directly connect that to the GraphQL queries you’ve attached to your components with Apollo Client.</p>



<p>It’s that kind of full-stack integration where GraphQL really shines, and I can’t wait to see what else will be possible!</p>


Daily Slack reports of your GraphQL query performance and errors

Reusable GraphQL schema directives

GraphQL over REST with Node, Heroku, and Apollo Engine


<p><a href="https://www.apollographql.com/docs/engine/" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;is a GraphQL gateway that provides caching, performance monitoring, and other features specifically for GraphQL. It’s built from the ground up to empower product developers to feel confident about using GraphQL on top of existing infrastructure.</p>



<p>Today, we’re launching the 1.0 version of the&nbsp;<code>apollo-engine</code>&nbsp;npm package and our standalone Docker container. These new releases make it dramatically easier to add Engine to your server.</p>



<p>In the past, you had to add code in several places and attach middleware to your app in a specific order, but now it’s much clearer where everything needs to go for a production-ready setup.</p>



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



<p>Apollo Engine provides a ton of valuable features to help you work with GraphQL, and can handle millions or even billions of requests a day, but at the same time we want to make sure it’s a breeze to get started with.</p>



<p>If you want to use Engine with Apollo Server and Node.js, setup is now as simple as can be:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// Install and import the apollo-engine package
const { ApolloEngine } = require(&#039;apollo-engine&#039;);
const { graphqlExpress } = require(&#039;apollo-server-express&#039;);

const app = express();

// Enable tracing and cacheControl in Apollo Server
app.use(&#039;/graphql&#039;, graphqlExpress({
  tracing: true,
  cacheControl: true,
  schema: schema,
  // ... other options
});

// Initialize Engine with an API key
const engine = new ApolloEngine({ apiKey: &#039;API_KEY&#039; });

// Replace app.listen() with engine.listen()
engine.listen({
  port: 3000,
  expressApp: app,
});</code></pre>



<p>You can get an API key by logging into the&nbsp;<a href="https://engine.apollographql.com/" target="_blank" rel="noreferrer noopener">Apollo Engine app</a>. Once you put in the API key, run your server, and execute some queries, you’ll be able to see traces of your queries, track errors, set up caching, and more!</p>



<p>For all of the details, read the setup directions in the docs:</p>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/engine/setup-node.html" target="_blank" rel="noreferrer noopener">For Node.js</a></li><li><a href="https://www.apollographql.com/docs/engine/setup-standalone.html" target="_blank" rel="noreferrer noopener">For other languages</a></li></ul>



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



<p>This new release comes with several improvements that make Engine easier to use while expanding support to more servers.</p>



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



<p>We’ve updated the API and documentation to make it easier to set things up correctly. The previous API required code to be added in very specific places, and the new one is much easier to explain and use correctly.</p>



<p>If you are already using Engine, upgrading is easy:</p>



<ul class="wp-block-list"><li>Instead of using a middleware like&nbsp;<code>engine.expressMiddleware()</code>, you replace your app’s&nbsp;<code>app.listen(port)</code>&nbsp;call with&nbsp;<code>engine.listen({ port, expressApp: app })</code>. This reduces code duplication and removes the need to worry about middleware ordering.</li><li>Instead of the&nbsp;<code>Engine</code>&nbsp;constructor with an&nbsp;<code>engineConfig: {...}</code>&nbsp;option, you now import an&nbsp;<code>ApolloEngine</code>&nbsp;constructor which takes the Engine config directly. Any Node-specific options are passed into the&nbsp;<code>listen</code>&nbsp;function above. This helps avoid confusion about where configuration should be passed.</li></ul>



<p>For all of the details,&nbsp;<a href="https://www.apollographql.com/docs/engine/1.0-migration.html" target="_blank" rel="noreferrer noopener">read the upgrade guide in the docs</a>.</p>



<h3 class="wp-block-heading" id="3111"><a href="#expanded-node-web-framework-support" aria-hidden="true" class="aal_anchor" id="expanded-node-web-framework-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>Expanded Node web framework support</h3>



<p>Because the new API relies on the standard Node&nbsp;<code>listen</code>&nbsp;interface instead of framework-specific middlewares, we’ve&nbsp;<a href="https://www.apollographql.com/docs/engine/setup-node.html#not-express" target="_blank" rel="noreferrer noopener">expanded our support of Node server frameworks</a>. Engine now supports Express, Hapi, Koa, Micro, Restify, Meteor, and even the built in&nbsp;<code>http.Server</code>.</p>



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



<p>Even thought it’s easy to install with npm, the part of Engine that you run inside your server is written in Go for better performance and stability. In the previous version, the web framework middleware you installed routed GraphQL requests to the Engine binary, and they were routed back to actually execute your GraphQL schema. With the new 1.0 API, all requests hit the Engine binary directly, and non-graphql requests are passed through. This new approach involves fewer roundtrips, making it even better than the previous approach while actually being easier to set up.</p>



<h3 class="wp-block-heading" id="2200"><a href="#easier-to-use-with-non-node-servers" aria-hidden="true" class="aal_anchor" id="easier-to-use-with-non-node-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>Easier to use with non-Node servers</h3>



<p>We’ve always distributed the Engine proxy binary both via the apollo-engine npm module (for use with Node GraphQL servers) and as a standalone Docker container (for other servers). We’ve made two improvements to how we support non-Node servers. First, we’re now using the same version numbers to tag the Docker container as we are for the npm module. So today is version 1.0.1 of both distributions, and the same&nbsp;<a href="https://www.apollographql.com/docs/engine/proxy-release-notes.html" target="_blank" rel="noreferrer noopener">release notes</a>&nbsp;describe updates to both distributions. Secondly, because we know it’s not easy to run Docker containers in every hosting environment, we’ve added a&nbsp;<a href="https://www.apollographql.com/docs/engine/setup-standalone.html#apollo-engine-launcher" target="_blank" rel="noreferrer noopener">new ApolloEngineLauncher API to the npm module</a>&nbsp;which you can use to run the Engine binary as a standalone process with no Node web framework integration.</p>



<h2 class="wp-block-heading" id="9d3c"><a href="#what-youll-see-in-the-engine-ui" aria-hidden="true" class="aal_anchor" id="what-youll-see-in-the-engine-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>What you’ll see in the Engine UI</h2>



<p>Once you get Engine set up, you’ll be able to look at&nbsp;<a href="https://www.apollographql.com/docs/engine/performance.html" target="_blank" rel="noreferrer noopener">detailed traces of your GraphQL queries</a>:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="596" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-1024x596.png" alt="" class="wp-image-838" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-1024x596.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-300x175.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-768x447.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-1536x894.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-2048x1192.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-1200x698.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-PiUjyhfH11jkzBLAmmTTQ-1980x1152.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Track your query performance distribution over time:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="348" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_vv0hvvbZzjP0igz_S00uXg-1024x348.png" alt="" class="wp-image-837" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_vv0hvvbZzjP0igz_S00uXg-1024x348.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_vv0hvvbZzjP0igz_S00uXg-300x102.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_vv0hvvbZzjP0igz_S00uXg-768x261.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_vv0hvvbZzjP0igz_S00uXg-1200x407.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_vv0hvvbZzjP0igz_S00uXg.png 1532w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p><a href="https://www.apollographql.com/docs/engine/caching.html" target="_blank" rel="noreferrer noopener">Cache GraphQL results</a>&nbsp;to make common queries resolve in a matter of microseconds:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="380" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_4z5FSggjOdHGzC7qXw1zKQ-1024x380.png" alt="" class="wp-image-836" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_4z5FSggjOdHGzC7qXw1zKQ-1024x380.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4z5FSggjOdHGzC7qXw1zKQ-300x111.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4z5FSggjOdHGzC7qXw1zKQ-768x285.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4z5FSggjOdHGzC7qXw1zKQ-1200x446.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4z5FSggjOdHGzC7qXw1zKQ.png 1406w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>And more — there are a lot of other capabilities that you can learn about in the&nbsp;<a href="https://www.apollographql.com/docs/engine/" target="_blank" rel="noreferrer noopener">Engine docs</a>. We’ve hand-picked this set of functionality over the last two years of talking to companies using GraphQL in production.</p>



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



<p>In addition to overhauling the API you use to set up Apollo Engine in your app, we’ve also started a total rework of&nbsp;<a href="https://www.apollographql.com/docs/engine/" target="_blank" rel="noreferrer noopener">our documentation</a>, beginning with the setup instructions. Keep an eye on our blog over the next few weeks to learn more about what Apollo Engine is, how it’s getting easier to use, and what features we’re working on next!</p>


Set up GraphQL caching and performance monitoring in minutes


<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

Universal GraphQL


<p>With the ever-nearing release of&nbsp;<a href="https://dev-blog.apollodata.com/whats-coming-in-apollo-client-2-0-bcd8ea64acbd" target="_blank" rel="noreferrer noopener">Apollo Client 2.0,</a>&nbsp;there’s no better time to learn some of the new features that make the 2.0 the most flexible and powerful version ever.</p>



<p>One of the ways to leverage this new flexibility is by using the&nbsp;<a href="https://github.com/apollographql/apollo-link" target="_blank" rel="noreferrer noopener">Apollo Link library</a>&nbsp;to customize what happens each time you send an operation to Apollo. Links are designed to be composed together to form control flow chains to manage a request, and they can be used as:</p>



<ul class="wp-block-list"><li>Middleware to perform side effects, modify the operation, or even just provide developer tools like logging.</li><li>Afterware which process the result of an operation, handle errors, or even save the data to multiple locations.</li><li>Network fetchers including HTTP, websockets, and even across the react-native bridge to the native network stack.</li></ul>



<p>This article will outline some of the core concepts to get you started. For a deeper dive, checkout the new&nbsp;<a href="https://www.apollographql.com/docs/link/" target="_blank" rel="noreferrer noopener">link docs!</a></p>



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



<p>One of the authors of Apollo Link,&nbsp;<a href="https://medium.com/u/712ce1f56160?source=post_page-----f0719d8193ee----------------------" target="_blank" rel="noreferrer noopener">Evans Hauser,</a>&nbsp;does a great job of outlining the goals of the package in his&nbsp;<a href="https://dev-blog.apollodata.com/apollo-link-the-modular-graphql-network-stack-3b6d5fcf9244" target="_blank" rel="noreferrer noopener">introductory post</a>. Building on top of that knowledge, the library is designed to be a powerful way to compose actions around data handling with GraphQL. Each link represents a subset of functionality that can be composed with other links to create complex control flows of data. At a basic level, a link is a function that takes a GraphQL request and returns an observable. To learn more about observables, take a look at the proposal&nbsp;<a href="https://github.com/tc39/proposal-observable" target="_blank" rel="noreferrer noopener">here</a>&nbsp;and read the incredible work of&nbsp;<a href="https://medium.com/u/da6839d28258?source=post_page-----f0719d8193ee----------------------" target="_blank" rel="noreferrer noopener">Ben Lesh</a>&nbsp;such as&nbsp;<a href="https://medium.com/@benlesh/learning-observable-by-building-observable-d5da57405d87" target="_blank" rel="noreferrer noopener">this article</a>.</p>



<p>A individual link isolate parts of the control flow of your GraphQL request into a single unit. For example, you could have a link that logs errors to your monitoring tool of choice. This error link doesn’t need to know anything else about how you are executing your request, just that it starts with an operation and eventually data will hopefully come back.</p>



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



<p>At the core of a link is the&nbsp;<code>request</code>&nbsp;method. A link’s request is called every time&nbsp;<code>execute</code>&nbsp;is run on that link chain. The request is where the operation is given to the link to return back data of some kind. Depending on where the link is in the stack, it will either use the second parameter to a link (the next link in the chain) or return back an&nbsp;<code>ExecutionResult</code>&nbsp;on its own.</p>



<p>The full description of a link’s request can be represented like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">type Context = { [key: string]: any };

interface Operation {
  query: DocumentNode;
  variables: { [key: string]: any };
  operationName: string;
  extensions?: { [key: string]: any };
  getContext(): Context;
  setContext(newContext: Context | (prevContext: Context) =&gt; Context): void;
  toKey(): string;
}

type NextLink = (operation: Operation) =&gt; Observable&lt;ExecutionResult&gt;

type RequestHandler = (operation: Operation, forward: NextLink) =&gt; Observable&lt;ExecutionResult&gt;
</code></pre>



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



<p>Since link chains have to fetch data at some point, they have the concept of a terminating link and non-terminating links. Simply enough, the terminating link is the one that doesn’t use the&nbsp;<code>forward</code>&nbsp;argument, but instead turns the operation into the result directly. Typically, this is done with a network request, but the possibilities are endless of how this can be done. The terminating link is the last link in the composed chain.</p>



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



<p>Links are meant to be composed into a single chain to handle an operation. Because of this, they need an easy way to send metadata about the request down the chain. They also need a way for the operation to send specific information to a link no matter where it was added to the chain. This is very similar to how context works in React. To accomplish this, each operation has a context object which can be accessed and manipulated by each link. For example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">const link = new ApolloLink((operation, forward) =&gt; {
  operation.setContext({ start: new Date() });
  return forward(operation).map((data) =&gt; {
    const time = new Date() - operation.getContext().start;
    console.log(`operation ${operation.operationName} took ${time} to complete`);
    return data;
  })
})</code></pre>



<p>Each context can be set by the operation it was started on. For example with Apollo Client:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">const link = new ApolloLink((operation, forward) =&gt; {
  const { saveOffline } = operation.getContext();
  if (saveOffline) // do offline stuff
  return forward(operation);
})

const client = new ApolloClient({
  cache: new InMemoryCache()
  link,
});

// send context to the link
const query = client.query({
  query: MY_GRAPHQL_QUERY,
  context: {
    saveOffline: true
  }
});</code></pre>



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



<p>Since links represent small portions of how you want your GraphQL operation to be handled, in order to serve all of the needs of your app they designed to be composed with other links as needed. Composition is managed in two main ways: additive and directional. Additive composition is how you can combine multiple links into a single chain, and directional is how you can control which links are used depending on the operation.</p>



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



<p>Apollo Link ships with two ways to compose links. The first is a method called <code>from </code>which is both exported, and is on the <code>ApolloLink</code> interface. <code>from </code>takes an array of links and combines them all into a single link. For example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">import { ApolloLink } from &#039;apollo-link&#039;;
import { RetryLink } from &#039;apollo-link-retry&#039;;
import { HttpLink } from &#039;apollo-link-http&#039;;
import MyAuthLink from &#039;../auth&#039;;

const link = ApolloLink.from([
  new RetryLink(),
  new AuthLink(),
  new HttpLink({ uri: &#039;/graphql&#039; })
]);</code></pre>



<p><code>from</code> is typically used when you have many links to join together all at once. The alternative way to join links is the <code>concat</code> method which joins two links together into one.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { ApolloLink } from &#039;apollo-link&#039;;
import { RetryLink } from &#039;apollo-link-retry&#039;;
import { HttpLink } from &#039;apollo-link-http&#039;;

const link = ApolloLink.concat(new RetryLink(), (new HttpLink({ uri: &#039;/graphql&#039; }));</code></pre>



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



<p>Given that links are a way of implementing custom control flow for your GraphQL operation, Apollo Link provides and easy way to use different links depending on the operation itself (or any other global state). This is done using the <code>split</code> method which is exported as a function and is on the <code>ApolloLink</code> interface. Using the split function can be done like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { ApolloLink } from &#039;apollo-link&#039;;
import { RetryLink } from &#039;apollo-link-retry&#039;;
import { HttpLink } from &#039;apollo-link-http&#039;;

const link = new RetryLink().split(
  (operation) =&gt; operation.getContext().version === 1,
  new HttpLink({ uri: &quot;/v1/graphql&quot; }),
  new HttpLink({ uri: &quot;/v2/graphql&quot; })
);</code></pre>



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



<p>Links are typically created and shared between every request in your application. However, most links do the same thing for each request and don’t need any knowledge about other operations being performed. These links are called stateless links because they have no shared execution state between requests. Stateless links can be written as simple functions wrapped in the <code>ApolloLink</code> interface. For example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { ApolloLink } from &#039;apollo-link&#039;;

const consoleLink = new ApolloLink((operation, forward) =&gt; {
  console.log(`starting request for ${operation.operationName}`);
  return forward(operation).map((data) =&gt; {
    console.log(`ending request for ${operation.operationName}`);
    return data;
  })
})</code></pre>



<p>Stateless links can also be written by extending the <code>ApolloLink</code> class and overwriting the request method. This is one way to store information about an individual link for each request.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">import { ApolloLink } from &#039;apollo-link&#039;;

class ReportErrorLink extends ApolloLink {
  constructor(errorCallback) {
    super();
    this.errorCallback = errorCallback;
  }
  request(operation, forward) {
    const observer = forward(operation);
    // errors will be sent to the errorCallback
    observer.subscribe({ error: this.errorCallback })
    return observer;
  }
}

const link = new ReportErrorLink(console.error);</code></pre>



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



<p>Sometimes a link may have different behavior based on other requests that are being executed. One such example is a link to batch requests into a single HTTP request instead of sending many at slightly different times. In order to do this, links can keep track of all operations being sent through them. The operation has a <code>toKey</code> method which will return a unique string based on the operation. Using this, you can write a link that manages application state easily:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">import { ApolloLink } from &#039;apollo-link&#039;;

class OperationTimingLink extends ApolloLink {
  constructor() {
    super();
    this.operations = {};
  }
  request(operation, forward) {
    const key = operation.toKey();
    if (!this.operations[key]) this.operations[key] = {}
    this.operations[key].start = new Date();
    return forward(operation).map((data) =&gt; {
        this.operations[key].elapsed = new Date() - this.operations[key].start;
        return data;
    });
  }
}

const link = new OperationTimingLink();</code></pre>



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



<p>The goal of Apollo Link is to provide a huge degree of flexibility to customize your GraphQL application to just what your app needs. In the future, we hope to see a number of links available on npm just like react components are today. Pick and choose what you want your app to be, compose them together, and let Apollo Client handle the rest!</p>



<p>Special thanks to&nbsp;<a href="https://medium.com/u/712ce1f56160?source=post_page-----f0719d8193ee----------------------" target="_blank" rel="noreferrer noopener">Evans Hauser</a>,&nbsp;<a href="https://medium.com/u/c827782c6410?source=post_page-----f0719d8193ee----------------------" target="_blank" rel="noreferrer noopener">Peggy Rayzis</a>&nbsp;and&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----f0719d8193ee----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;for making Apollo Link such a powerful and fun library to work with!</p>


Creating a data component with Apollo Link

Tutorial: Pagination

Server Side Rendering with GraphQL


<p>You’ve probably encountered a library before which serves all of your needs, except for a handful of unsupported corner cases. Even though they might not be widely needed features, they cause a huge pain in your app. That’s why we’re working on a library called Apollo Link, which addresses this issue for today’s GraphQL clients by providing a framework to give you complete control over GraphQL request control flow and result resolution.</p>



<p>To speed up development time, the Apollo Link package contains a collection of Links that each perform a discrete function commonly found in GraphQL network stacks. The behavior of these links ranges from simple HTTP requests, to subscriptions over websockets, to modifying request control flow with retrying, polling, batching, and deduplicating.</p>



<p>These basic links, together with any custom links you build for your app, can be composed together to combine their functionality, creating a GraphQL client with custom behavior. When a link is added to the middle of a chain, the link applies its modification to the request’s control flow, such as retrying. The resulting link can return a GraphQL&nbsp;<code>ExecutionResult</code>(data + errors). This can be anything from mocked data, local application state, or, more often, the result of a request to your GraphQL Server.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="829" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_rNvNCLyvcOtDmwn23Nyt0A-1024x829.png" alt="" class="wp-image-1027" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_rNvNCLyvcOtDmwn23Nyt0A-1024x829.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rNvNCLyvcOtDmwn23Nyt0A-300x243.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rNvNCLyvcOtDmwn23Nyt0A-768x621.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_rNvNCLyvcOtDmwn23Nyt0A.png 1048w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The HTTP Link</figcaption></figure>



<p>To support the diverse behavioral requirements of GraphQL applications, each GraphQL response is represented by an Observable. Observables expose a subscribe method that takes three callbacks: next, error, and complete. Next can be called zero, once, or many times, until either the error or complete callbacks are made. This structure of callbacks is ideal because it provides the power to represent current and planned GraphQL results, including queries, mutations, subscriptions, and even live queries.</p>



<h2 class="wp-block-heading" id="376e"><a href="#creating-your-first-apollo-link" aria-hidden="true" class="aal_anchor" id="creating-your-first-apollo-link"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 your first Apollo Link</h2>



<p>In this blog post, we will gradually build up a custom GraphQL client with Apollo Links that provides results to GraphiQL.</p>



<p>The foundation of all GraphQL clients, is fetching a GraphQL result. So we’ll start by building a link that can make an HTTP request. This link will be a helpful example for other custom transports, such as using a Firebase endpoint, XHR, a REST endpoint, or other GraphQL endpoint. All Links inherit from a base class that provides the methods for composition, and are required to implement the&nbsp;<code>request</code>&nbsp;method.</p>



<p>Check out the implementation in the CodeSandbox below:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Http Link" width="580" height="870" src="https://codesandbox.io/embed/59xjvgnwa#?secret=GNBLYtURm5" data-secret="GNBLYtURm5"></iframe>
</div></figure>



<h2 class="wp-block-heading" id="21bc"><a href="#creating-an-apollo-link-composition" aria-hidden="true" class="aal_anchor" id="creating-an-apollo-link-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>Creating an Apollo Link Composition</h2>



<p>Now that we have our custom transport link, the next goal is to add some request control flow with links. To illustrate, we are going to create one link that catches errors and routes them to GraphQL data and another link that logs the operations and results. The logging link will be applied first, then the catch link; finally, the http link will fetch the request.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="327" height="339" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_62VLGUaU-9ULCoBCGvgdkQ.png" alt="" class="wp-image-1026" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_62VLGUaU-9ULCoBCGvgdkQ.png 327w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_62VLGUaU-9ULCoBCGvgdkQ-289x300.png 289w" sizes="(max-width: 327px) 100vw, 327px" /><figcaption>Ordering of Link Application</figcaption></figure>



<p>In order to make the chain work, the logging and catch link need access to the next link. To accomplish this, the&nbsp;<code>request</code>&nbsp;method has access to the&nbsp;<code>forward</code>&nbsp;argument, a function that pass the operation to the next link returns the observable result. Finally, we create a composed chain of the links with the static&nbsp;<code>from</code>&nbsp;method of&nbsp;<code>ApolloLink</code>.</p>



<p>See the implementation of the chain below:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Log, Catch, and Http Link" width="580" height="870" src="https://codesandbox.io/embed/wm5qq6vdm#?secret=iACm8M7yUE" data-secret="iACm8M7yUE"></iframe>
</div></figure>



<h2 class="wp-block-heading" id="d795"><a href="#modifying-specific-graphql-requests" aria-hidden="true" class="aal_anchor" id="modifying-specific-graphql-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>Modifying specific GraphQL requests</h2>



<p>Great! Now we have the ability to control the flow of a request and response through our GraphQL client. What if we want different behavior for mutations and queries? This example uses a different endpoint for mutations, reroutes errors on queries only, and logs all requests. Additionally we might want to selectively modify an operation while using the same transport, for example adding another variable to a query with a certain operation name. ApolloLink provides the ability to specify a certain portion of a composition to run depending on the operation with the&nbsp;<code>split</code>&nbsp;method.</p>



<p>Look at the implementation below:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Splits, Log, Catch, and Http Link" width="580" height="870" src="https://codesandbox.io/embed/25zww2am#?secret=GjTWt8TI39" data-secret="GjTWt8TI39"></iframe>
</div></figure>



<h2 class="wp-block-heading" id="6829"><a href="#building-your-own-graphql-client" aria-hidden="true" class="aal_anchor" id="building-your-own-graphql-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>Building your own GraphQL client</h2>



<p>Awesome! Now we have the ability to create a completely custom GraphQL client that can run logic and fetch results on a per query basis. Apollo Link provides many basic links that can be combine and extended with your own links to create the behavior required by your application. You can find the currently offered links in the&nbsp;<a href="https://github.com/apollographql/apollo-link/" target="_blank" rel="noreferrer noopener">Apollo Link repository</a>.</p>



<p>The Apollo Link ecosystem is constantly evolving, and entirely community driven. If you are interested in contributing, or shaping the future of GraphQL client customization, please open an issue or pull request. If you want some ideas of how to start contributing, join the&nbsp;<a href="https://www.apollodata.com/#slack" target="_blank" rel="noreferrer noopener">Apollo Slack</a>&nbsp;and send me (evans) a private message!</p>



<p>In the future, look out for posts about communicating between links using the context field in the GraphQL operation, stateful vs stateless links, publishing your own link configuration, adding type safety, and more!</p>



<p>If you want to keep updated on Apollo Link, 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="https://twitter.com/evanshauser" target="_blank" rel="noreferrer noopener">@evanshauser</a>.</p>



<p>Thank you to&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----c865be0ce059----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>,&nbsp;<a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----c865be0ce059----------------------" target="_blank" rel="noreferrer noopener">James Baxley III</a>, and&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----c865be0ce059----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>&nbsp;for greatly informing the Apollo Link design process and their continued support of the author!</p>


Apollo Link: Creating your custom GraphQL client


<p>Scala is an excellent language for writing GraphQL apps, especially with the awesome&nbsp;<a href="http://sangria-graphql.org/" target="_blank" rel="noreferrer noopener">Sangria</a>&nbsp;library for writing GraphQL servers by&nbsp;<a href="https://medium.com/u/93c50e4b5ebe?source=post_page-----b066c6b09af4----------------------" target="_blank" rel="noreferrer noopener">Oleg Ilyenko</a>. Scala is a powerful language, combining object oriented and functional programming concepts to make writing complex applications easy. The functional programming aspects of Scala are especially helpful when writing GraphQL schemas, allowing you to declare resolvers without any boilerplate.</p>



<p>With&nbsp;<a href="https://www.scala-js.org/" target="_blank" rel="noreferrer noopener">Scala.js</a>, you can now use Scala to write client-side apps, by writing Scala code that compiles to JavaScript that runs in your browser. With a straightforward interop layer between Scala and JavaScript, it’s easy to use frameworks like React and Angular to create Scala.js apps. And starting today, Apollo joins in the fun with a new library for using Apollo Client with React in Scala:&nbsp;<a href="https://github.com/apollographql/react-apollo-scalajs" target="_blank" rel="noreferrer noopener">react-apollo-scalajs</a>!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="550" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Z2aNrRtgSImSfGA-G-_dBg-1024x550.png" alt="" class="wp-image-1032" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_Z2aNrRtgSImSfGA-G-_dBg-1024x550.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Z2aNrRtgSImSfGA-G-_dBg-300x161.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Z2aNrRtgSImSfGA-G-_dBg-768x412.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Z2aNrRtgSImSfGA-G-_dBg-1200x644.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_Z2aNrRtgSImSfGA-G-_dBg.png 1278w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>Adding the react-apollo graphql HOC in Scala</figcaption></figure>



<h2 class="wp-block-heading" id="03ef"><a href="#introducing-a-hrefhttps-github-com-apollographql-react-apollo-scalajs-target_blank-relnoreferrer-noopenerreact-apollo-scalajs-a" aria-hidden="true" class="aal_anchor" id="introducing-a-hrefhttps-github-com-apollographql-react-apollo-scalajs-target_blank-relnoreferrer-noopenerreact-apollo-scalajs-a"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/react-apollo-scalajs&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;react-apollo-scalajs&lt;/a&gt;</code></h2>



<p>As its name suggests,&nbsp;<code>react-apollo-scalajs</code>&nbsp;provides the glue to use Apollo Client with React in your Scala.js app. Beyond providing static typing facades for Apollo Client,&nbsp;<code>react-apollo-scalajs</code>&nbsp;includes layers that allow you to use Apollo Client through idiomatic Scala code. For example, results of queries are returned as Scala&nbsp;<code>Futures</code>&nbsp;and query results can be implicitly converted into fragments they can be viewed as.</p>



<p>Through the excellent&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/apollo-codegen&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;apollo-codegen&lt;/a&gt;</code>&nbsp;tool, which is currently used for generating static types for Swift, TypeScript, and Flow, you can now generate Scala case classes which represent the responses of GraphQL queries you will be running in your app. With strong query typing, most issues can be caught at compile-time, with&nbsp;<code>react-apollo-scalajs</code>&nbsp;performing extra type checks as you set up React components to receive query results.</p>



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



<p><em>Download and run&nbsp;</em><a href="https://github.com/apollographql/react-apollo-scalajs/tree/master/example" target="_blank" rel="noreferrer noopener"><em>the example on GitHub</em></a><em>!</em></p>



<p>To demonstrate how you can use&nbsp;<code>react-apollo-scalajs</code>&nbsp;, let’s go through a quick example of putting together an app with queries and mutations targeting a GraphQL server on&nbsp;<a href="https://launchpad.graphql.com/" target="_blank" rel="noreferrer noopener">Apollo Launchpad</a>.</p>



<p>First, set up your project by installing the Scala.js plugin and the necessary library dependencies.</p>



<p>In your <code>project/plugins.sbt</code> add the Scala.js plugin and the <a rel="noreferrer noopener" href="https://scalacenter.github.io/scalajs-bundler/" target="_blank">Scala.js Bundler</a> plugin (for Webpack-based bundling):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-scala">addSbtPlugin(&quot;org.scala-js&quot; % &quot;sbt-scalajs&quot; % &quot;0.6.18&quot;)

addSbtPlugin(&quot;ch.epfl.scala&quot; % &quot;sbt-scalajs-bundler&quot; % &quot;0.7.0&quot;)</code></pre>



<p>And in your <code>build.sbt</code> specify the Scala version, add NPM and Scala library dependencies, and configure the code generator:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-scala">
enablePlugins(ScalaJSBundlerPlugin)

resolvers += &quot;Apollo Bintray&quot; at &quot;https://dl.bintray.com/apollographql/maven/&quot;
libraryDependencies += &quot;com.apollographql&quot; %%% &quot;react-apollo-scalajs&quot; % &quot;0.1.0&quot;

libraryDependencies += &quot;me.shadaj&quot; %%% &quot;slinky-web&quot; % &quot;0.1.0&quot;

npmDependencies in Compile += &quot;react&quot; -&gt; &quot;15.6.1&quot;

npmDependencies in Compile += &quot;react-dom&quot; -&gt; &quot;15.6.1&quot;

npmDependencies in Compile += &quot;react-apollo&quot; -&gt; &quot;1.4.8&quot;

scalaJSUseMainModuleInitializer := true

val namespace = &quot;com.apollographql.scalajs&quot;

(sourceGenerators in Compile) += Def.task {
  import scala.sys.process._

  val out = (sourceManaged in Compile).value

  out.mkdirs()

  Seq(
    &quot;apollo-codegen&quot;, &quot;generate&quot;, ((sourceDirectory in Compile).value / &quot;graphql&quot;).getAbsolutePath + &quot;/*.graphql&quot;,
    &quot;--schema&quot;, (baseDirectory.value / &quot;schema.json&quot;).getAbsolutePath,
    &quot;--target&quot;, &quot;scala&quot;,
    &quot;--namespace&quot;, namespace,
    &quot;--output&quot;, (out / &quot;graphql.scala&quot;).getAbsolutePath
  ).!
  Seq(out / &quot;graphql.scala&quot;)
}

watchSources ++= ((sourceDirectory in Compile).value / &quot;graphql&quot; ** &quot;*.graphql&quot;).get</code></pre>



<p>Eventually, the source generators configuration at the end of the file will be moved into an SBT plugin, but for now it is necessary to include this in all projects.</p>



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



<p>Before we jump into using GraphQL for loading our data, let’s start by setting up a simple React UI to verify that our setup works. Create a file <code>src/main/scala/com/apollographql/scalajs/Main.scala</code> where we’ll put the initializer for our application. For using React in Scala, we’ll use <a rel="noreferrer noopener" href="https://github.com/shadaj/slinky" target="_blank">Slinky</a>, which makes React in Scala look very similar to React in plain JavaScript.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-scala">package com.apollographql.scalajs

import me.shadaj.slinky.web.ReactDOM
import me.shadaj.slinky.web.html._ // imports tags, such as &quot;h1&quot;

import scala.scalajs.js.JSApp
import org.scalajs.dom.{document, html}

import scala.scalajs.js

object Main extends JSApp {
  override def main(): Unit = { // called when the app launches
    val reactContainer = document.createElement(&quot;div&quot;)
    document.body.appendChild(reactContainer)

    ReactDOM.render(
      h1(&quot;hello!&quot;), // this is Scala&#039;s version of JSX!
      reactContainer
    )
  }
}</code></pre>



<p>If you run&nbsp;<code>sbt fastOptJS::startWebpackDevServer</code>&nbsp;you should be able to navigate to&nbsp;<a href="http://localhost:8080/webpack-dev-server," target="_blank" rel="noreferrer noopener">http://localhost:8080/webpack-dev-server,</a>&nbsp;select the&nbsp;<code>main-bundle</code>&nbsp;and see your app running live!</p>



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



<p>Now that we have a simple app set up, we can add use GraphQL to load data for it! For this example, we will be running GraphQL queries against the Apollo Launchpad at <a rel="noreferrer noopener" href="https://launchpad.graphql.com/1jzxrj179" target="_blank">https://launchpad.graphql.com/1jzxrj179</a>, loading and displaying posts in our app. First, we add the GraphQL query for loading all posts. In <code>src/main/graphql/posts.graphql</code> add the query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query AllPosts {
  posts {
    id
    title
    votes
  }
}</code></pre>



<p>If you run&nbsp;<code>sbt/compile</code>&nbsp;you’ll see that the code generator kicks in (make sure you have previously run&nbsp;<code>npm i -g apollo-codegen</code>&nbsp;) and emits static types for our query to&nbsp;<code>target/scala-2.12/src_managed/main/graphql.scala</code>&nbsp;. We can now use these static types to power our React app!</p>



<p>Wiring GraphQL data into a component through <code>react-apollo-scalajs</code> is just like using Apollo in your JS code. First, we create a component to receive the data from our query. In <code>src/main/scala/com/apollographql/scalajs/PostsView.scala</code> we set up a new component:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-scala">package com.apollographql.scalajs

import me.shadaj.slinky.core.StatelessComponent
import me.shadaj.slinky.core.facade.ReactElement
import me.shadaj.slinky.web.html._

import scala.scalajs.js
import scala.scalajs.js.annotation.ScalaJSDefined

object PostsView extends StatelessComponent {
  type Props = AllPostsQuery.Props // we use the static Props type from our generated code as the props for 
  // this is where we create the definition class, which maps to an ES6 class for defining a component
  
  @ScalaJSDefined
  class Def(jsProps: js.Object) extends Definition(jsProps) {
    override def render(): ReactElement = {
      div(
        props.data.map[ReactElement] { d =&gt; // if we have a result
          d.posts.toList.flatten.flatten.map { post =&gt;
            // for each not-null post (we use flattens here to remove the null values)
            div(key := post.id.toString)( // render the post
              h1(post.title.getOrElse[String](&quot;Unknown title&quot;)),
              h2(post.votes.getOrElse(0).toString)
            )
          }
        }.getOrElse[ReactElement](h1(&quot;loading!&quot;))
      )
    }
  }
  
  // wire the component to our query using the familiar graphql method
  val WithData = graphql(AllPostsQuery)(this)
}</code></pre>



<p>And that’s it! You now have a React component that’s wired to a GraphQL query. The last step is to adjust our application initializer to wrap the application inside an&nbsp;<code>ApolloProvider</code>&nbsp;and configure Apollo Client to run queries against the Launchpad server.</p>



<p>First, at the top of our main method, we initialize Apollo Client:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-scala">val client = ApolloClient(ApolloClientOptions(
  networkInterface = Some(createNetworkInterface(NetworkInterfaceOptions(
    uri = Some(&quot;https://1jzxrj179.lp.gql.zone/graphql&quot;)
  )))
))</code></pre>



<p>Then we replace the contents inside <code>ReactDOM.render</code> to render our new component inside an <code>ApolloProvider</code> wrapper.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-scala">ReactDOM.render(
  ApolloProvider(ApolloProvider.Props(client))(
    div(
      PostsView.WithData(()) // we pass in () because there are no variables for the query
    )
  ),
  reactContainer
)</code></pre>



<p>If you run&nbsp;<code>sbt fastOptJS::startWebpackDevServer</code>&nbsp;again and reload the application page you should see a working GraphQL app, showing “Loading” and then displaying the posts data!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="432" height="472" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_Fe5MeClWAi2C8uKdEfTVxA.gif" alt="" class="wp-image-1031"/><figcaption>It works!</figcaption></figure>



<p>You now have a working GraphQL application written in Scala that uses Apollo Client and React! There are a lot more things that&nbsp;<code>react-apollo-scalajs</code>&nbsp;supports, such as query variables and mutations, so check out the&nbsp;<code>examples</code>&nbsp;folder in the&nbsp;<a href="https://github.com/apollographql/react-apollo-scalajs" target="_blank" rel="noreferrer noopener">repository</a>&nbsp;to see how to use those features. This is still a very initial release of Scala.js support for Apollo, so please let us know at&nbsp;<a href="http://github.com/apollographql/react-apollo-scalajs/issues" target="_blank" rel="noreferrer noopener">http://github.com/apollographql/react-apollo-scalajs/issues</a>&nbsp;if you find any bugs or have ideas for new features.</p>


Using Scala.js with React and GraphQL


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This is a follow up to a similar post on using Flow and Apollo which can be found&nbsp;<a href="https://dev-blog.apollodata.com/a-stronger-typed-react-apollo-c43bd52be0d8" target="_blank" rel="noreferrer noopener">here</a>.</p></blockquote>



<p>When the Apollo team started out to build a flexible and incrementally adoptable GraphQL client, one of the early&nbsp;<a href="https://github.com/apollographql/apollo-client/issues/6" target="_blank" rel="noreferrer noopener">discussions</a>&nbsp;centered around static typing for the library code. Since the library deals with a complex data types (like the parsed abstract syntax tree of a GraphQL operation), it seemed like making the code type safe was a needed addition.</p>



<p>The team investigated both Flow and TypeScript, and ultimately went with TypeScript for its active development, editor integration, and strong tooling. It’s been a huge help ever since.</p>



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



<p>Even though Apollo Client and React Apollo are both written in TypeScript, the actual type usage for application developers was not as strong as it should have been. In many places, React Apollo used either&nbsp;<code>any</code>, essentially bypassing static types, or left types off all together where allowed.</p>



<p>Luckily, thanks to the efforts of&nbsp;<a href="https://medium.com/u/ce97660ec72?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Ian Ker-Seymer,</a>&nbsp;these shortcomings were brought to the attention of the Apollo team. With his help, application developers can opt in to much stronger TypeScript checking of their React apps!</p>



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



<p><strong>This article will follow the same progression as the&nbsp;</strong><a href="https://dev-blog.apollodata.com/a-stronger-typed-react-apollo-c43bd52be0d8" target="_blank" rel="noreferrer noopener"><strong>article on Flow</strong></a><strong>,&nbsp;</strong>and it also assumes you already have TypeScript configured in your project. If you don’t, check out this&nbsp;<a href="https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter" target="_blank" rel="noreferrer noopener">great starter tooling from Microsoft</a>.</p>



<p>We will start with a simple React component wrapped with the <code>graphql</code> higher order component (HOC) from React Apollo. This component will display a hero from Star Wars and their friends, with data returned from a GraphQL endpoint:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">import React from &quot;react&quot;;
import gql from &quot;graphql-tag&quot;;
import { graphql } from &quot;react-apollo&quot;;

export const HERO_QUERY = gql`
  query GetCharacter($episode: Episode!) {
    hero(episode: $episode) {
      name
      id
      friends {
        name
        id
        appearsIn
      }
    }
  }
`;

export const withCharacter = graphql(HERO_QUERY, {
  options: () =&gt; ({
    variables: { episode: &quot;JEDI&quot; },
  }),
});

export default withCharacter(({ data: { loading, hero, error } }) =&gt; {
  if (loading) return &lt;div&gt;Loading&lt;/div&gt;;
  if (error) return &lt;h1&gt;ERROR&lt;/h1&gt;;
  return (
    &lt;div&gt;
      {hero &amp;&amp;
        &lt;div&gt;
          &lt;h3&gt;{hero.name}&lt;/h3&gt;
          {hero.friends.map(friend =&gt;
            &lt;h6 key={friend.id}&gt;
              {friend.name}:
              {&quot; &quot;}{friend.appearsIn.map(x =&gt; x.toLowerCase()).join(&quot;, &quot;)}
            &lt;/h6&gt;
          )}
        &lt;/div&gt;}
    &lt;/div&gt;
  );
}</code></pre>



<p>The above code pulls some data from a GraphQL API using a query and includes lifecycle information, such as loading and error information. With a few minor changes, we can tell Typescript how to support us in writing code within this render function.</p>



<p>Let’s walk through what is happening in this diff.</p>



<ol class="wp-block-list"><li>We need to tell TypeScript what the shape of our data from our graphql server will look like. We manually write the types for our response data. Alternatively, you can use&nbsp;<a href="https://github.com/apollographql/apollo-codegen" target="_blank" rel="noreferrer noopener">apollo-codegen</a>&nbsp;to generate the types for you! Shoutout to&nbsp;<a href="https://medium.com/u/2ab2eb7f698c?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Lewis Chung</a>&nbsp;for working to make this easier and&nbsp;<a href="https://medium.com/u/592c66ff70d?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Martijn Walraven</a>&nbsp;and&nbsp;<a href="https://medium.com/u/abc034e10a70?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Robin Ricard</a>&nbsp;for the codegen framework!</li></ol>



<pre class="wp-block-preformatted">+ export type Hero = {
+   name: string;
+   id: string;
+   appearsIn: string[];
+   friends: Hero[];
+ };

+ export type Response = {
+   hero: Hero,
+ };</pre>



<p>2. The last line is where the magic happens. We tell TypeScript what the shape of the result will look like from the server when the graphql enhancer wraps a component.</p>



<p>If you already had your project set up with TypeScript, and have already typed your response data, all you have to do is add the type to the&nbsp;<code>graphql</code>&nbsp;HOC and you are off!</p>



<p>The immediate benefits can be seen by writing some bad code! Let’s make a mistake and see what happens:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-tsx">export default withCharacter(({ loading, hero, error }) =&gt; {
  // Operator &#039;&gt;&#039; cannot be applied to types &#039;boolean&#039; and &#039;number&#039;.
  if (loading &gt; 1) return &lt;div&gt;Loading&lt;/div&gt;;
  if (error) return &lt;h1&gt;error.name&lt;/h1&gt;;
  return ...;
}</code></pre>



<p>Since <code>withCharacter</code> is now typed, TypeScript will error out preventing a potential production bug!</p>



<figure class="wp-block-embed is-type-photo is-provider-giphy"><div class="wp-block-embed__wrapper">
<a href="https://giphy.com/gifs/what-hello-loki-Bjx0A3RTcVtUA"><img loading="lazy" decoding="async" src="https://media0.giphy.com/media/Bjx0A3RTcVtUA/giphy.gif" alt="Follow What GIF - Find &amp; Share on GIPHY" width="500" height="246" /></a>
</div></figure>



<h2 class="wp-block-heading" id="78eb"><a href="#taking-control-of-your-tree" aria-hidden="true" class="aal_anchor" id="taking-control-of-your-tree"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 control of your tree</h2>



<p>Wrapped components are almost always exported and used by a component somewhere else in your tree, so if your exported component has prop requirements, we need to tell TypeScript so it can help prevent errors elsewhere in our tree. Since the <code>graphql</code> wrapper supports polymorphic types, we can use the second type parameter of it to do just that! Let’s make a change to our initial component that converts it to use a prop called <code>episode</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">+ export type InputProps = {
+  episode: string,
+ };

+ export const withCharacter = graphql&lt;Response, InputProps&gt;(HERO_QUERY, {
- export const withCharacter = graphql&lt;Response&gt;(HERO_QUERY, {
+   options: ({ episode }) =&gt; ({
+     variables: { episode },
-   options: () =&gt; ({
-     variables: { episode: &quot;JEDI&quot; },
  }),
});</code></pre>



<p>We can define the props that our exported component will need (<code>InputProps</code>) and attach them to our enhancer using the second type argument. Now our component can pass <code>episode</code> to pick which characters to load and TypeScript can know how to enforce that! In practice it would look like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-tsx">import React from &quot;react&quot;;
import ApolloClient, { createNetworkInterface } from &quot;apollo-client&quot;;
import { ApolloProvider } from &quot;react-apollo&quot;;

import Character from &quot;./Character&quot;;

export const networkInterface = createNetworkInterface({
  uri: &quot;https://mpjk0plp9.lp.gql.zone/graphql&quot;,
});
export const client = new ApolloClient({ networkInterface });

export default () =&gt;
  &lt;ApolloProvider client={client}&gt;
    // Type &#039;{}&#039; is not assignable to type &#039;Readonly&lt;InputProps&gt;&#039;.
    // Property &#039;episode&#039; is missing in type &#039;{}&#039;.
    &lt;Character /&gt;
  &lt;/ApolloProvider&gt;;</code></pre>



<p>The other benefit we get is typing of the <code>options</code> function itself. Let’s say we forgot what props are passed into our component and we thought the episode was a number:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">export const withCharacter: OperationComponent&lt;Response, InputProps&gt; = graphql(HERO_QUERY, {
  options: ({ episode }) =&gt; ({
    // Operator &#039;&gt;&#039; cannot be applied to types &#039;string&#039; and &#039;number&#039;.
    variables: { episode: episode &gt; 1 },
  })
});</code></pre>



<p>Thanks TypeScript!</p>



<figure class="wp-block-embed is-type-photo is-provider-giphy"><div class="wp-block-embed__wrapper">
<a href="https://giphy.com/gifs/filmeditor-will-ferrell-elf-xUySTu7FXFYo6nXWWQ"><img loading="lazy" decoding="async" src="https://media0.giphy.com/media/xUySTu7FXFYo6nXWWQ/giphy.gif" alt="Will Ferrell Thank You GIF by filmeditor - Find &amp; Share on GIPHY" width="480" height="270" /></a>
</div></figure>



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



<p>GraphQL is awesome at allowing you to only request the data you want from the server. The client still often needs to reshape or do client side calculations based on these results. React Apollo has a handy dandy props function which lets you reshape the resulting props into a new object. In practice, I use this for almost every enhancer I write.</p>



<p><em>Note: It also pairs nicely with&nbsp;</em><a href="http://ramdajs.com/" target="_blank" rel="noreferrer noopener"><em>Ramda</em></a><em>&nbsp;for some fun, fun functional code.</em></p>



<p>Since this function can shape passed props, plus a potential data result, potential error, and loading state, having it strongly typed would prevent a lot of <em>save => see error => check data => save</em> workflows. Let’s take a look at how to set this up with React Apollo:</p>



<p>The most important part of the change above is including what the result of the props function will look like on line 5.</p>



<p>Now, let’s check it out in action a couple of weeks after we first wrote this file and forgot some things.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">export const withCharacter = graphql&lt;Response, InputProps, Props&gt;(HERO_QUERY, {
  options: ({ episode }) =&gt; ({
    variables: { episode },
  }),
  props: ({ data, ownProps }) =&gt; ({
    ...data,
    // Operator &#039;&gt;&#039; cannot be applied to types &#039;string&#039; and &#039;number&#039;.
    episode: ownProps.episode &gt; 1,
    // Property &#039;isHero&#039; does not exist on type &#039;Hero&#039;.
    isHero: data &amp;&amp; data.hero &amp;&amp; data.hero.isHero,
  }),
});</code></pre>



<ol class="wp-block-list"><li>The first error shows we don’t have a good memory around what an episode represents. Maybe we should change it to&nbsp;<code>episodeName</code>&nbsp;! Luckily, TypeScript has our back.</li><li>I really thought we had an isHero field in our query? Whelp, looks like we don’t based on the types.</li></ol>



<p>These two examples show type checking passed props and resulting data as well as the fact that data may not have arrived yet from the server!</p>



<figure class="wp-block-embed is-type-photo is-provider-giphy"><div class="wp-block-embed__wrapper">
https://giphy.com/gifs/broad-city-hillary-clinton-3osxYdwmc9Oy8H7h7i
</div></figure>



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



<p>I hope that this article shows both how awesome TypeScript is, and how subtle the differences between Flow and TypeScript can be for application developers. They are both amazing choices!</p>



<p>I’d like to give a special thanks to&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>,&nbsp;<a href="https://medium.com/u/2ab2eb7f698c?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Lewis Chung</a>,&nbsp;<a href="https://medium.com/u/b1f108c2bfa9?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Brett Jurgens</a>,&nbsp;<a href="https://github.com/ianks" target="_blank" rel="noreferrer noopener">Ian</a>, and&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----a9aa2c7dcf87----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;for reviewing the initial type PR. I’ve also&nbsp;<a href="https://github.com/apollographql/react-docs/pull/258" target="_blank" rel="noreferrer noopener">started the effort to include documentation</a>&nbsp;for Flow and TypeScript in the official React docs.<br></p>


Getting started with TypeScript and Apollo


<p>Late last year,&nbsp;<a href="https://medium.com/u/47b3b199a712?source=post_page-----2481f8bcdd55----------------------" target="_blank" rel="noreferrer noopener">Danielle Man</a>&nbsp;blogged about the&nbsp;<a href="https://dev-blog.apollodata.com/apollo-client-developer-tools-ff89181ebcf" target="_blank" rel="noreferrer noopener">Apollo Client Developer Tools</a>&nbsp;Chrome extension, which helps you debug your Apollo-Client-based GraphQL app. The Dev Tools launched with three main features, and we’re excited to announce the first major addition today!</p>



<ol class="wp-block-list"><li>Built-in Graph<em>i</em>QL query IDE</li><li>Watched queries inspector</li><li><strong>Mutation log (</strong><a href="https://github.com/apollographql/apollo-client-devtools/pull/36" target="_blank" rel="noreferrer noopener"><strong>new</strong></a><strong>!)</strong></li><li>Store inspector</li></ol>



<p>It’s been really exciting to see the reception of this tool in the last few months, and it now has over 8,000 downloads on the Chrome store. In this post, we’ll highlight the purpose of each feature and walk you through how you might use it during app development.</p>



<p><em>If you want to follow along, get started by&nbsp;</em><a href="https://chrome.google.com/webstore/detail/apollo-client-developer-t/jdkknkkbebbapilgoeccciglkfbmbnfm?hl=en-US" target="_blank" rel="noreferrer noopener"><em>installing the Apollo Client Devtools extension</em></a><em>&nbsp;from the Chrome store.</em></p>



<h2 class="wp-block-heading" id="68e0"><a href="#graphiql-query-explorer" aria-hidden="true" class="aal_anchor" id="graphiql-query-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>Graph<em>i</em>QL query explorer</h2>



<p>The main use case of Graph<em>i</em>QL is to run queries against your server to explore the data available in the API. You can easily see if your client instance is configured correctly and if your sever is returning the data you expect.</p>



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



<p>The best part of having Graph<em>i</em>QL built into the dev tools is that queries are sent from your already configured Apollo Client instance, so you don’t have to manually pass in headers and other data or manually configure a Graph<em>i</em>QL page in your app. This makes it super easy to test different queries in your app and be confident that you’re using the correct setup.<br><br>To demonstrate this feature, let’s test out some queries in Graph<em>i</em>QL in&nbsp;<a href="http://www.githunt.com/" target="_blank" rel="noreferrer noopener">GitHunt</a>, our live Apollo Client example app. Once you’ve navigated to&nbsp;<a href="http://www.githunt.com/" target="_blank" rel="noreferrer noopener">www.githunt.com</a>, open the Apollo Client DevTools by opening the Chrome devtools console and clicking on the Apollo tab at the far right. This should take you right to Graph<em>i</em>QL. Now, we can query the server for the repository, name, and description of each element in the new repositories feed by writing the following query into the left side of the console and clicking the play button.</p>



<pre class="wp-block-preformatted">query {<br>  feed(type:NEW) {<br>    repository {<br>      name<br>      full_name<br>      description<br>    }<br>  }<br>}</pre>



<p>If you have the dev tools installed correctly, it will look like this:</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="704" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-1024x704.png" alt="" class="wp-image-1050" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-1024x704.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-300x206.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-768x528.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-1536x1056.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-2048x1409.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-1200x825.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4_QfLuxXM8jH2L_8LbnY-w-1980x1362.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The data returned by the query will be displayed on the right side of the console.</figcaption></figure>



<p>The results returned by the query will be displayed on the right side of the console. This lets you easily test out different queries against your server’s schema while developing your frontend.</p>



<p>You can also try out Graph<em>i</em>QL’s auto-complete feature and see more about the schema for the GitHunt example app by typing&nbsp;<code>query { }</code>&nbsp;and then typing “ctrl+space” within the curly braces to see what fields pop up. You can also use the handy “Docs” button in the top right to see complete documentation about the schema.</p>



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



<p>The watched queries inspector allows us to view the watched queries and query variables on a page, as well as any errors thrown by that query. A&nbsp;<em>watched query</em>&nbsp;is a query that is currently being used by a component in the app.</p>



<p>Developers often split up the queries used by one page of an app into multiple files or fragments in the source code, making it cumbersome to view the entire query in one place and test out modifications. The watched queries inspector combines these fragmented queries into one query string in your developer console, saving you many roundtrips between the source code to collect the full query.</p>



<p>Try out the watched queries inspector on GitHunt by clicking on the “queries” button on the left panel of the extension. The left side of the new view will display a list of watched queries on the page. To view the query used to display the home page feed, click on the&nbsp;<code>Feed</code>&nbsp;query, and then open the “Query string” dropdown.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="800" height="550" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_uAO7svCttRwADHUf6aZGuw.gif" alt="" class="wp-image-1049"/></figure>



<p>One of our favorite features is that you can then easily run the query in the GraphiQL console with the “run in GraphiQL” button.</p>



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



<p>This is the newest feature of the dev tools released just a few days ago. Thanks to awesome contributors&nbsp;<a href="https://github.com/ryannealmes" target="_blank" rel="noreferrer noopener">Ryan-Neal Mes</a>&nbsp;and&nbsp;<a href="https://github.com/rrdelaney" target="_blank" rel="noreferrer noopener">Ryan Delaney</a>&nbsp;for contributing and reviewing this major new feature!</p>



<p>With the mutation log, you can see the most recent mutations done through Apollo Client, see the query and variables, and then test them out yourself via GraphiQL:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="669" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_F13vzDLyt0BmqXJp51jMKg-1024x669.png" alt="" class="wp-image-1048" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_F13vzDLyt0BmqXJp51jMKg-1024x669.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_F13vzDLyt0BmqXJp51jMKg-300x196.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_F13vzDLyt0BmqXJp51jMKg-768x502.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_F13vzDLyt0BmqXJp51jMKg-1200x784.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_F13vzDLyt0BmqXJp51jMKg.png 1338w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>This new panel has a ton of potential. For example, in the future it might be able to help you debug your mutation&nbsp;<code>update</code>&nbsp;functions or see how optimistic UI is working. If you have an idea, please&nbsp;<a href="https://github.com/apollographql/apollo-client-devtools" target="_blank" rel="noreferrer noopener">file an issue or open a PR</a>!</p>



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



<p>The store inspector allows you to view all data loaded from active queries and mutations and provides insight into how Apollo Client’s normalized caching works under the hood. Examples of these on the GitHunt site include 1) prefetching comment data into the store on comment mouse-over, and 2) the noticeable difference between temporary and permanent ID creation for comments while they are being saved to the server.<br><br>Let’s take a look. Navigate back to GitHunt, open the dev tools and click on the “Store” tab in the left panel. The left side of the newly-opened tab will display the root query object and a list of all object IDs currently in the store.</p>



<figure class="wp-block-image alignfull size-large"><img loading="lazy" decoding="async" width="1024" height="643" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-1024x643.png" alt="" class="wp-image-1047" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-1024x643.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-300x188.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-768x482.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-1536x964.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-2048x1285.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-1200x753.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_PoZ5g-jIoKO-fqI0bl847w-1980x1242.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Clicking on each individual object will show you the data that Apollo Client has loaded for each entry in the feed.</p>



<p>Navigating to another page on the site and fetching new data will put that data in our store. For example, let’s look at&nbsp;<code>Entry63</code>, the object in the store that represents&nbsp;<code>facebook/graphql</code>. If we click on “view comments” on the&nbsp;<code>facebook/graphql</code>&nbsp;repository and submit a comment, we can see that the data from the added comment has been added to the store.</p>



<h3 class="wp-block-heading" id="2cc3"><a href="#why-not-redux-dev-tools" aria-hidden="true" class="aal_anchor" id="why-not-redux-dev-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>Why not Redux dev tools?</h3>



<p>All of the data loaded with Apollo Client is actually being stored in Redux, so why not just use the Redux dev tools for this? Well, it’s actually possible to view the underlying Redux state directly, as shown below. That can be useful if you really want to dig into the implementation.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="636" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-1024x636.png" alt="" class="wp-image-1046" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-1024x636.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-300x186.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-768x477.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-1536x955.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-2048x1273.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-1200x746.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_ySv8CrMPbTUuWANBBve5dg-1980x1230.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>However, it can be a bit difficult to decipher the data in that format. The store feature of the Apollo Client dev tools displays the same data in a more GraphQL-specific format, making it easier to read.</p>



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



<p>You can use the store inspector to see how the data in the store changes after mutations, as shown in the below gif. To test this out for yourself, try using the extension while doing&nbsp;<a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">this tutorial</a>&nbsp;on GraphQL mutations, written by&nbsp;<a href="https://medium.com/@helfer" target="_blank" rel="noreferrer noopener">Jonas</a>. Here’s a quick preview:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="800" height="475" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_nFVkckF1dAVcvXB1C01b9w.gif" alt="" class="wp-image-1045"/></figure>



<h2 class="wp-block-heading" id="9156"><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’ve heard from many people that the developer tools are one of the reasons they love using Apollo Client to load data in their app. We agree, and our ultimate goal is to create a GraphQL experience where you can easily understand and inspect what’s going on, every step of the way.</p>



<p>We’re excited to put some focused effort into the Apollo Client Dev Tools this summer, and we’ll keep you updated as we fix current issues and add new features. Next up: Better performance and stability in apps with a very large amount of data, and support for FireFox!</p>



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



<p><em>Ramya studies Computer Science at MIT and is joining us for the summer as an intern at Apollo. Be sure to follow along with her work on&nbsp;</em><a href="https://twitter.com/rrramyan" target="_blank" rel="noreferrer noopener"><em>Twitter</em></a><em>.</em></p>



<p><em>If you’re as excited about advancing GraphQL technology and enabling developers as we are,&nbsp;</em><a href="https://www.meteor.io/jobs/" target="_blank" rel="noreferrer noopener"><em>we’re hiring</em></a><em>!</em></p>


Inspecting your GraphQL client in the browser


<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="(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

Building React Apps with GraphQL, Graphcool & Apollo


<p>React Native enables you to use the same programming language and mental model you use to write web applications to create great native mobile experiences. Similarly, GraphQL and&nbsp;<a href="http://dev.apollodata.com/" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;are designed to make data loading and management simple and consistent, regardless of your client platform or backend data store.</p>



<p>In this post I’ll show you how these two technologies can work together seamlessly in React Native’s new FlatList component. As you follow along with the post, try the live demo and even run it on your mobile device with Expo Snack:&nbsp;<a href="https://snack.expo.io/HJc-0uygW" target="_blank" rel="noreferrer noopener">https://snack.expo.io/HJc-0uygW</a></p>



<figure class="wp-block-image size-large"><a href="https://snack.expo.io/HJc-0uygW"><img loading="lazy" decoding="async" width="1024" height="720" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_dot66NVkAguqiuTo9O48uw-1024x720.png" alt="" class="wp-image-1121" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_dot66NVkAguqiuTo9O48uw-1024x720.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dot66NVkAguqiuTo9O48uw-300x211.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dot66NVkAguqiuTo9O48uw-768x540.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dot66NVkAguqiuTo9O48uw-1200x844.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_dot66NVkAguqiuTo9O48uw.png 1400w" sizes="(max-width: 1024px) 100vw, 1024px" /></a></figure>



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



<p>One of the most common UI features in a mobile app is the scrollable list. Since most apps need to display long lists of data and mobile devices don’t have much screen space, it’s important to get the right user experience. Less than two months ago, around React Conf 2017, the React Native team announced a new set of components specifically made for building these views with React:&nbsp;<a href="https://facebook.github.io/react-native/blog/2017/03/13/better-list-views.html" target="_blank" rel="noreferrer noopener">FlatList and friends.</a></p>



<p>In this article, we’ll look at the convenient APIs FlatList provides, and how they pair nicely with the features provided by GraphQL and Apollo Client.&nbsp;With these tools, you can build great user experiences without introducing complicated, hard-to-maintain UI or data management code.</p>



<h3 class="wp-block-heading" id="fa4b"><a href="#whats-so-great-about-react-native-flatlist" aria-hidden="true" class="aal_anchor" id="whats-so-great-about-react-native-flatlist"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 so great about React Native FlatList?</h3>



<p>It has all of the features you need to build a great native list view, with all of the bells and whistles users expect: Infinite scroll pagination, pull to refresh, and smooth rendering performance. Here’s a minimal example from the&nbsp;<a href="https://facebook.github.io/react-native/docs/flatlist.html" target="_blank" rel="noreferrer noopener">React Native documentation</a>:</p>



<pre class="wp-block-preformatted">&lt;FlatList<br>  data={[{key: 'a'}, {key: 'b'}]}<br>  renderItem={({item}) =&gt; &lt;Text&gt;{item.key}&lt;/Text&gt;}<br>/&gt;</pre>



<p>Getting a basic list displayed is simple, but how do you take advantage of all of these nice features I just mentioned? Well, it can be helpful to have a data loading library that makes loading state, refetching, and pagination easy.</p>



<h2 class="wp-block-heading" id="3c5c"><a href="#setting-up-flatlist-and-apollo-client" aria-hidden="true" class="aal_anchor" id="setting-up-flatlist-and-apollo-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>Setting up FlatList and Apollo Client</h2>



<p>Today, we’re going to focus on the props needed to set up the above features in&nbsp;<code>FlatList</code>, and see how simple it is to wire up Apollo Client to interact with them.</p>



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



<p>To start, we need a GraphQL API from which we can load data. Since we’re focusing on the client we’ll just use the&nbsp;<a href="http://api.githunt.com/graphiql?query=%7B%0A%20%20feed%20(type%3A%20TOP%2C%20limit%3A%2020%2C%20offset%3A%200)%20%7B%0A%20%20%20%20repository%20%7B%0A%20%20%20%20%20%20owner%20%7B%20login%20%7D%0A%20%20%20%20%20%20name%0A%20%20%20%20%7D%0A%0A%20%20%20%20postedBy%20%7B%20login%20%7D%0A%20%20%7D%0A%7D%0A" target="_blank" rel="noreferrer noopener">API from our GitHunt example app</a>, but it’s not too hard to&nbsp;<a href="https://dev-blog.apollodata.com/react-graphql-tutorial-part-2-server-99d0528c7928" target="_blank" rel="noreferrer noopener">set up a server yourself</a>.</p>



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



<p>Before we can test out fancy features, we’ll need to load some initial data. With GraphQL and the&nbsp;<code>react-apollo</code>&nbsp;higher-order component, wiring up a query to our React component is just one function call:</p>



<pre class="wp-block-preformatted">const FeedWithData = graphql(<br>  gql`<br>    query Feed($pageSize: Int!, $offset: Int!) {<br>      feed (type: TOP, limit: $pageSize, offset: $offset) {<br>        repository {<br>          name<br>          owner { login }<br>          stargazers_count<br>        }<br>    <br>        postedBy { login }<br>      }<br>    }<br>  `,<br>  {<br>    options: {<br>      notifyOnNetworkStatusChange: true,<br>      variables: { offset: 0, pageSize: PAGE_SIZE },<br>    },<br>  }<br>)(Feed);</pre>



<p>This code looks simple because people like&nbsp;<a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----9646fa9a199b----------------------" target="_blank" rel="noreferrer noopener">James Baxley</a>&nbsp;in the Apollo community have worked hard to make the library easy to use, but it’s actually doing a lot under the hood:</p>



<ol class="wp-block-list"><li>Checking the cache of existing data to avoid extra data loading</li><li>Keeping track of fine-grained loading status for the query</li><li>Reading data out of the cache, delivering it to the&nbsp;<code>Feed</code>&nbsp;component, and watching for further cache updates</li></ol>



<p>In this code, we configure the query with two variables — a page size we’ll use as the&nbsp;<code>limit</code>&nbsp;argument, and the current&nbsp;<code>offset</code>&nbsp;we’re looking at. To achieve pagination, we’ll later pass new values for these variables.</p>



<p>In addition to doing a lot of helpful bookkeeping, Apollo also adds a lot of useful information and methods to the prop it passes down. Let’s see how we can connect those to&nbsp;<code>FlatList</code>&nbsp;to get the features we need.</p>



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



<p>Pull to refresh is the feature that enables you to pull down on the top of a list view to get fresh data.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="800" height="547" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_6d-B9eEjMaEc9pU-eednug.gif" alt="" class="wp-image-1120"/><figcaption>Try it yourself:&nbsp;<a href="https://snack.expo.io/HJc-0uygW" target="_blank" rel="noreferrer noopener">https://snack.expo.io/HJc-0uygW</a></figcaption></figure>



<p>To get this, you need to pass in two props to&nbsp;<code>FlatList</code>:</p>



<ol class="wp-block-list"><li><code>refreshing</code>&nbsp;— A boolean that indicates whether or not a pull to refresh is currently in progress. We can easily get this from&nbsp;<a href="http://dev.apollodata.com/react/api-queries.html#graphql-query-data-networkStatus" target="_blank" rel="noreferrer noopener">Apollo’s&nbsp;</a><code>&lt;a href=&quot;http://dev.apollodata.com/react/api-queries.html#graphql-query-data-networkStatus&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;networkStatus&lt;/a&gt;</code><a href="http://dev.apollodata.com/react/api-queries.html#graphql-query-data-networkStatus" target="_blank" rel="noreferrer noopener">&nbsp;prop</a>, which provides a value of&nbsp;<code>4</code>&nbsp;when a query is currently refetching.</li><li><code>onRefresh</code>&nbsp;— A callback for when pull to refresh is activated by a user swiping down. This can be wired directly to&nbsp;<a href="http://dev.apollodata.com/react/api-queries.html#graphql-query-data-refetch" target="_blank" rel="noreferrer noopener">Apollo’s refetch method</a>, which will also set the network status for the&nbsp;<code>refreshing</code>&nbsp;prop above.</li></ol>



<p>So, all together, it’s only<em>&nbsp;two lines of code</em>&nbsp;to connect Apollo and the React Native FlatList to add pull to refresh:</p>



<pre class="wp-block-preformatted">refreshing={data.networkStatus === 4}<br>onRefresh={() =&gt; data.refetch()}</pre>



<p>And with that, we get fully native pull to refresh behavior!</p>



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



<p>For application performance, it’s important to not load or display data the user isn’t looking at yet. A common technique for this is&nbsp;<em>infinite scroll pagination</em>&nbsp;— giving the impression of an unending list by loading new items just in time when we are about to run out of content to display:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="800" height="548" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_iH7rz7vabHW7opH1noDfCQ.gif" alt="" class="wp-image-1119"/><figcaption>Try it yourself:&nbsp;<a href="https://snack.expo.io/HJc-0uygW" target="_blank" rel="noreferrer noopener">https://snack.expo.io/HJc-0uygW</a></figcaption></figure>



<p>Adding this is almost as simple as pull to refresh above. We just need to provide one prop to&nbsp;<code>FlatList</code>, the&nbsp;<code>onEndReached</code>&nbsp;callback. Here’s the code:</p>



<pre class="wp-block-preformatted">onEndReached={() =&gt; {<br>  data.fetchMore({<br>    variables: { offset: data.feed.length + 1 },<br>    updateQuery: (previousResult, { fetchMoreResult }) =&gt; {<br>      // Don't do anything if there weren't any new items<br>      if (!fetchMoreResult || fetchMoreResult.feed.length === 0) {<br>        return previousResult;<br>      }      return {<br>        // Append the new feed results to the old one<br>        feed: previousResult.feed.concat(fetchMoreResult.feed),<br>      };<br>    },<br>  });<br>}}</pre>



<p>The callback from&nbsp;<code>FlatList</code>&nbsp;wires up nicely to the&nbsp;<code>fetchMore</code>&nbsp;method from the Apollo Client data object. It reuses the same query we saw above, but passes in a new&nbsp;<code>offset</code>&nbsp;variable to fetch a page of data after the items we have already seen. Then, we use a simple concat to add the items to the end, and they show up in the UI seamlessly!</p>



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



<p>In the Apollo community, we’re passionate about doing for data loading what React Native is doing for native UI development. We want to enable product developers to spend less time managing data and more time building a great application. Because Apollo Client includes critical boilerplate-reducing features such as network status tracking, refetching, pagination, caching, and more, building a fully-functional list view in React native on top of your GraphQL API is just a few lines of code, and that leaves you with a lot less code to worry about and maintain.</p>



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



<p><em>If you’re excited about developer ergonomics and you want to help build a next-generation data loading experience, please join the Apollo community and contribute, or&nbsp;</em><a href="https://www.meteor.io/jobs/#5e11e6cf-5303-4c12-a3e7-11e5f8da4be1" target="_blank" rel="noreferrer noopener"><em>apply for a full-time job</em></a><em>&nbsp;as an open source engineer!</em></p>


Building a great scrollable list in React Native with FlatList


<p>This is part 4 of our Full-stack React + GraphQL tutorial series. Each part is self-contained and introduces one new, key concept, so you can either do each part separately or follow the entire series — it’s up to you!</p>



<p>Here are the sections we’ve covered so far:</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: The Frontend</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-part-2-server-99d0528c7928" target="_blank" rel="noreferrer noopener">Part 2: The Server</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">Part 3: Basic GraphQL Mutations</a></li><li>Part 4: Optimistic UI (you’re here)</li><li><a href="https://medium.com/p/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5: Input Types and Custom Resolvers</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-server-side-e51c32dc2951" target="_blank" rel="noreferrer noopener">Part 6: Subscriptions on the server</a></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>



<p>In this part, we’re going to dive a little bit deeper into how GraphQL mutations are handled on the client. We’ll take the list view and mutation from&nbsp;<a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">part 3</a>, simulate a network latency of 500 milliseconds, and then use store updates and Optimistic UI to make the latency all but disappear from the perspective of the user.</p>



<p>By the end of this tutorial, you’ll know how to use store updates and Optimistic UI to deal with network latency.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Hint: If something doesn’t work quite as expected, you can always check out the “solution” by running&nbsp;<code>&lt;em&gt;git checkout t4-end&lt;/em&gt;</code></p></blockquote>



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



<p>To get started, let’s clone the tutorial git repo and install 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 t4-start<br>cd server &amp;&amp; npm install &amp;&amp; cd ../client &amp;&amp; npm install &amp;&amp; cd ..</pre>



<p>To make sure it all worked as intended, let’s start the server and the client each in a separate terminal:</p>



<pre class="wp-block-preformatted">cd server<br>npm start</pre>



<p>In another terminal:</p>



<pre class="wp-block-preformatted">cd client<br>npm start</pre>



<p>If it worked, you should now see the ChannelsView from the end of part 3 in your browser:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="516" height="326" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_qAO-W1EVUaahaxDaoZ5dew.gif" alt="" class="wp-image-1126"/><figcaption>Adding a new channel — no latency</figcaption></figure>



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



<p>As you can see in the image above, any new channels you add show up in the list instantly. That’s great, because reactivity helps with great UX.</p>



<p>However, if you followed along in part 3, you might remember that this update actually does&nbsp;<strong>two roundtrips&nbsp;</strong>right now! One for the mutation request, and a second one to refetch the list after the mutation completed. The second roundtrip is currently necessary because there’s no way for the client to know that the new item you just added should be in the list. GraphQL simply doesn’t have any way of encoding that information because it treats the backend as a black box: query in → data out. Before we fix that, let’s see why it’s a problem.</p>



<p>In order to see what the UX would be like if the network was slower, we’re going to simulate a network latency of 500ms in Apollo’s network interface by adding a middleware.</p>



<p>To do so, add the following lines to&nbsp;<code>client/src/App.js</code>&nbsp;right after declaring the&nbsp;<code>networkInterface</code>&nbsp;constant.</p>



<pre class="wp-block-preformatted">// const networkInterface = ...<br>networkInterface.use([{<br>  applyMiddleware(req, next) {<br>    setTimeout(next, 500);<br>  },<br>}]);</pre>



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



<p>Now that we’ve added 500 ms of latency to every request, adding a new channel feels a bit different:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="434" height="326" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_GjaTShD0QgO8wPL2aQRF-A.gif" alt="" class="wp-image-1125"/><figcaption>Adding a new channel — 500 ms latency</figcaption></figure>



<p>The delay you see from the time the word “tennis” fades to the time it disappears is the time it takes for the mutation to complete its server roundtrip. The delay from the time the word “tennis” disappears in the input box until the time it appears is the latency of the list refetch query.</p>



<p>Even though refetching made it really easy and quick for us to build this feature in the first place, we need a better solution in a production app with users that experience latency. Right now, the experience for those users is not great: First, they wait and nothing happens; then, they see their input disappear completely, before it finally appears where they expected it.</p>



<p>Given that especially on mobile networks a few hundred milliseconds of latency is not uncommon, we need a way to deal with it. The first thing we can do is avoid the second roundtrip to refetch the list.</p>



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



<p>Lucky for us, the mutation already returns all the information we need to incorporate the new item into the list. We just have to tell Apollo Client how to do it for us!</p>



<p>For mutations and other cases where you need to update the store based on an action on the client, Apollo provides a set of powerful tools to perform imperative store updates:&nbsp;<code>readQuery</code>,<code>writeQuery</code>,&nbsp;<code>readFragment</code>&nbsp;and&nbsp;<code>writeFragment</code>. You can read all about them&nbsp;<a href="http://dev.apollodata.com/core/read-and-write.html" target="_blank" rel="noreferrer noopener">here</a>.</p>



<p>Because updating the store after a mutation is such a common use-case, Apollo Client makes it really easy to use these functions via the&nbsp;<code>update</code>&nbsp;property exposed in&nbsp;<code>mutate</code>.</p>



<p>To use it, let’s replace the&nbsp;<code>refetchQueries</code>&nbsp;option in&nbsp;<code>AddChannel.js</code>&nbsp;with the following call to&nbsp;<code>update</code>:</p>



<pre class="wp-block-preformatted">const handleKeyUp = (evt) =&gt; {<br>    if (evt.keyCode === 13) {<br>      evt.persist();<br>      mutate({ <br>        variables: { name: evt.target.value },<br>        <strong>update</strong>: (store, { data: { addChannel } }) =&gt; {<br>            // Read the data from the cache for this query.<br>            const data = store.readQuery({query: channelsListQuery });<br>            // Add our channel from the mutation to the end.<br>            data.channels.push(addChannel);<br>            // Write the data back to the cache.<br>            store.writeQuery({ query: channelsListQuery, data });<br>          },<br>      })<br>      .then( res =&gt; {<br>        evt.target.value = '';  <br>      });<br>    }<br>  };</pre>



<p>Now as soon as the mutation completes, we read the current result for the&nbsp;<code>channelsListQuery</code>&nbsp;out of the store, append the new channel to it, and tell Apollo Client to write it back to the store. That’s all we have to do! Our&nbsp;<code>ChannelsListWithData</code>&nbsp;component automatically will automatically get updated with the new data.</p>



<p>If you run another mutation, you’ll notice that there is no longer any delay between the time the input disappears and re-appears at the end of the list. It’s practically instantaneous, which is great!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="434" height="326" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_G8RNiFHyjUiWTMgYICcB2w.gif" alt="" class="wp-image-1124"/><figcaption>Adding a channel with “update”— 500 ms latency</figcaption></figure>



<p>The latency of the initial mutation is still there, but fortunately there’s a way to deal with that, too!</p>



<h2 class="wp-block-heading" id="3b87"><a href="#optimistic-ui" aria-hidden="true" class="aal_anchor" id="optimistic-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>Optimistic UI</h2>



<p>Apollo Client can simulate zero-latency server responses with a trick that’s generally called Optimistic UI. Optimistic UI is pretty tricky to set up manually, but thanks to the fact that Apollo manages both the store and the network requests for you, using Optimistic UI is really easy.</p>



<p>All you have to do to simulate a zero-latency server response is add the&nbsp;<code>optimisticResponse</code>&nbsp;property to your&nbsp;<code>mutate</code>&nbsp;call.&nbsp;<code>optimisticResponse</code>&nbsp;should be the response that you expect from the server. We already know the channel name that we expect. The ID isn’t that important yet, so we just take a random value to make sure there are no collisions. Finally, we also have to specify the&nbsp;<code>__typename</code>&nbsp;to make sure Apollo Client knows what kind of object it is:</p>



<pre class="wp-block-preformatted">mutate({ <br>  variables: { name: evt.target.value },<br>  <strong>optimisticResponse</strong>: {<br>     addChannel: {<br>       name: evt.target.value,<br>       id: Math.round(Math.random() * -1000000),<br>       __typename: 'Channel',<br>     },<br>   },<br>   update: ...<br>})</pre>



<p>If add the optimisticResponse to your code, you’ll notice that there’s no more delay between the time you hit return and the time the item shows up at the bottom of the list.</p>



<p>In fact, the optimisticResponse is so fast that the item will appear in the list even before it’s removed from the input field. This is because we have a snippet of code that clears the input field when the mutation successfully returned. Now that we have optimistic UI, that’s not really appropriate anymore. Instead, let’s give the user some visual feedback about which list items have already been confirmed by the server, and which ones haven’t.</p>



<p>To let the user know when a channel has not yet been confirmed by the server, we’ll need to somehow add that information to the item. Instead of modifying the server schema to keep track of some client state, we’re going to use a little hack here to keep track of which items are optimistic.</p>



<p>We know that all server-generated ids are positive integers, but the optimistically “generated” ids are all negative — how lucky! 😉</p>



<pre class="wp-block-preformatted">id: Math.round(Math.random() * -1000000),</pre>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Note: There are cleaner ways to keep track of optimistic items in your UI, but they require a bit more setup, so we’ll leave that for a future tutorial.</p></blockquote>



<p>To make the optimistic channels visually distinct, we give them an extra CSS class in&nbsp;<code>ChannelsListWithData.js</code>:</p>



<pre class="wp-block-preformatted">return (<br>    &lt;div className="channelsList"&gt;<br>      &lt;AddChannel /&gt;<br>      { channels.map( ch =&gt; <br>        (&lt;div key={ch.id} <strong>className={'channel ' + (ch.id &lt; 0 ? 'optimistic' : '')}</strong>&gt;{ch.name}&lt;/div&gt;)<br>      )}<br>    &lt;/div&gt;<br>  );</pre>



<p>Finally, we just have to define what that class looks like in&nbsp;<code>App.css</code>. For our purposes, we just make the text a bit more greyed out:</p>



<pre class="wp-block-preformatted">div.optimistic {<br>  color: rgba(255, 255, 255, 0.5);<br>}</pre>



<p>And that’s it! With these changes, the addChannel mutation should now look much better!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="434" height="326" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_fPHhXYMZOtpZzC9DY2KCsg.gif" alt="" class="wp-image-1123"/><figcaption>Adding a channel with “update” and “optimisticResponse” — 500 ms latency</figcaption></figure>



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



<h2 class="wp-block-heading" id="c3ad"><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>And with that, you’ve reached the end of part 4 in this tutorial series! You’ve learned how to use store updates and optimistic UI to hide network latency from your users. Together with Parts 1, 2 and 3 of this tutorial series, you’re now familiar with all the basics of writing a simple React + GraphQL app with great UX using Apollo.</p>



<p>In the&nbsp;<a href="https://medium.com/p/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">next part</a>&nbsp;of this series we’ll add a second view to the app and learn how to use cached data and prefetching to show previews and load pages faster. Make sure to subscribe if you don’t want to miss future parts!</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><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 <a rel="noreferrer noopener" href="https://twitter.com/apollographql" target="_blank">@apollographql</a> and <a rel="noreferrer noopener" href="https://twitter.com/helferjs" target="_blank">@helferjs</a>.</p></blockquote>


Tutorial: Speeding up GraphQL Mutations with optimistic UI


<p>There has been a lot of buzz about GraphQL Subscriptions in the community recently, and a lot of people are excited about the&nbsp;<a href="https://dev-blog.apollodata.com/the-next-step-for-realtime-data-in-graphql-b564b72eb07b#.w9zvvcjbh" target="_blank" rel="noreferrer noopener">subscriptions RFC</a>&nbsp;opened by Rob Zhu from Facebook.</p>



<p>If you haven’t tried GraphQL subscriptions yet, check out our docs to learn how to&nbsp;<a href="http://dev.apollodata.com/tools/graphql-subscriptions/index.html" target="_blank" rel="noreferrer noopener">add subscriptions to your existing Node.js GraphQL server</a>. You can also easily try building a React app with them by following&nbsp;<a href="https://www.graph.cool/docs/tutorials/worldchat-subscriptions-example-ui0eizishe/" target="_blank" rel="noreferrer noopener">Graphcool’s tutorial</a>.</p>



<p>Today, I want to tell you about something else that’s really cool: <strong>Did you know that </strong><a rel="noreferrer noopener" href="https://github.com/graphql/graphiql" target="_blank"><strong>Graph<em>i</em>QL</strong></a><strong> already supports subscriptions today? </strong>Don’t believe me? Here’s a demo so you can see for yourself:</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="GraphQL Subscriptions with GraphiQL over Githunt" width="580" height="326" src="https://www.youtube.com/embed/aAwZrBgmnho?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>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Check out the working example of GitHunt with Graph<strong>i</strong>QL&nbsp;<a href="https://github.com/apollographql/githunt-API" target="_blank" rel="noreferrer noopener">here</a>&nbsp;(and the React frontend&nbsp;<a href="http://github.com/apollographql/githunt-react" target="_blank" rel="noreferrer noopener">here</a>).</p></blockquote>



<h2 class="wp-block-heading" id="73e4"><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 standard GraphiQL library already supports passing in a fetcher that returns an observable&nbsp;<em>or</em>&nbsp;promise. That means that anyone can configure it with their own transport, even if it supports multiple results. We’ve already done that for you, using a new<code>&lt;a href=&quot;https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql-subscriptions-fetcher&lt;/a&gt;</code>, so you don’t have to.</p>



<p>The following steps are all you need to do. (We’re using&nbsp;<code>graphql-server-express</code>&nbsp;for the example.)</p>



<p>First, make sure you have the latest&nbsp;<code>graphql-server-express</code>&nbsp;package:</p>



<pre class="wp-block-preformatted">npm install —-save graphql-server-express</pre>



<p>Now, all you need to do is to set a new field we added to&nbsp;<code>graphqlExpress</code>&nbsp;config, called&nbsp;<code>subscriptionsEndpoint</code>, with the Websocket URL subscriptions endpoint (this is the same endpoint you use in your&nbsp;<code>SubscriptionClient</code>). For example:</p>



<pre class="wp-block-preformatted">app.use(‘/graphiql’, graphiqlExpress({<br>  endpointURL: ‘/graphql’,<br>  subscriptionsEndpoint: `ws://localhost:3000/subscriptions`,<br>}));</pre>



<p>That’s it! Finally, all you have to do is start your server, open your browser in&nbsp;<a href="http://api.githunt.com/graphiql" target="_blank" rel="noreferrer noopener">http://localhost:3000/graph<em>i</em>ql</a>, write a GraphQL subscriptions query inside, and the published data from the server will be pushed into your Graph<em>i</em>QL client and displayed in the result screen of Graph<em>i</em>QL.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This example uses GraphQL server with express — but it also works with graphql-server-hapi, Koa, Restify and Lambda. Just add the&nbsp;<code>&lt;em&gt;subscriptionsEndpoint&lt;/em&gt;</code>&nbsp;field to your GraphiQL configuration and you are good to go! You can also check out the live GitHunt example&nbsp;<a href="http://api.githunt.com/graphiql" target="_blank" rel="noreferrer noopener">here</a>.</p></blockquote>



<h2 class="wp-block-heading" id="d7b5"><a href="#what-if-you-dont-use-graphql-server" aria-hidden="true" class="aal_anchor" id="what-if-you-dont-use-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>What if you don’t use&nbsp;<a href="http://dev.apollodata.com/tools/graphql-server/index.html" target="_blank" rel="noreferrer noopener">graphql-server</a>?</h2>



<p>We added the new Graph<em>i</em>QL subscriptions support to&nbsp;<a href="http://dev.apollodata.com/tools/graphql-server/index.html" target="_blank" rel="noreferrer noopener">graphql-server</a>&nbsp;by default, but in case you’re not using it, it’s still very easy to add that support to your own server.</p>



<p>Graph<em>i</em>QL is usually served as static HTML (<a href="https://github.com/apollographql/graphql-server/blob/master/packages/graphql-server-module-graphiql/src/renderGraphiQL.ts#L39" target="_blank" rel="noreferrer noopener">here’s how we do it in graphql-server</a>), so first you need to load&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/subscriptions-transport-ws&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;subscriptions-transport-ws&lt;/a&gt;</code>&nbsp;and&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql-subscriptions-fetcher&lt;/a&gt;&nbsp;</code>inside the&nbsp;<code>&lt;head&gt;</code>&nbsp;tag. We’ve published the transport client so that it’s easy to use in a script tag from&nbsp;<a href="https://unpkg.com/" target="_blank" rel="noreferrer noopener">Unpkg</a>:</p>



<pre class="wp-block-preformatted">&lt;script src=”//unpkg.com/subscriptions-transport-ws@0.5.4/browser/client.js”&gt;&lt;/script&gt;&lt;script src="//unpkg.com/graphiql-subscriptions-fetcher@0.0.2/browser/client.js"&gt;&lt;/script&gt;</pre>



<p>Next, you need to create a&nbsp;<code>SubscriptionClient</code>&nbsp;with your subscriptions endpoint:</p>



<pre class="wp-block-preformatted">var subscriptionsClient = new window.SubscriptionsTransportWs.SubscriptionClient(‘YOUR_SUBSCRIPTIONS_ENDPOINT_HERE’, { reconnect: true });var subscriptionsFetcher = window.SubscriptionsTransportWs.graphQLFetcher(subscriptionsClient, graphQLFetcher);</pre>



<p>Finally, replace the regular&nbsp;<code>graphqlFetcher</code>&nbsp;you use in Graph<em>i</em>QL with the one that uses the fetcher from&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql-subscriptions-fetcher&lt;/a&gt;&nbsp;</code>when creating your Graph<em>i</em>QL instance:</p>



<pre class="wp-block-preformatted">ReactDOM.render(<br>  React.createElement(GraphiQL, {<br><strong>    fetcher: subscriptionsFetcher,</strong><br>    onEditQuery: onEditQuery,<br>    onEditVariables: onEditVariables,<br>    onEditOperationName: onEditOperationName,<br>    query: ${safeSerialize(queryString)},<br>    response: ${safeSerialize(resultString)},<br>    variables: ${safeSerialize(variablesString)},<br>    operationName: ${safeSerialize(operationName)},<br>}), document.body);</pre>



<p><a href="https://github.com/urigo/graphql-server/blob/feat/subscriptions-graphiql/packages/graphql-server-module-graphiql/src/renderGraphiQL.ts" target="_blank" rel="noreferrer noopener">Here</a>&nbsp;is a complete example of how it should look.</p>



<h2 class="wp-block-heading" id="33bb"><a href="#whats-happening-behind-the-scenes" aria-hidden="true" class="aal_anchor" id="whats-happening-behind-the-scenes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 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 happening behind the scenes?</h2>



<p><code>&lt;a href=&quot;https://github.com/apollographql/subscriptions-transport-ws&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;subscriptions-transport-ws&lt;/a&gt;</code>is a GraphQL subscriptions network transport. Loading it into Graph<em>i</em>QL client and replacing the&nbsp;<code>graphQLFetcher</code>&nbsp;function with&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql-subscriptions-fetcher&lt;/a&gt;</code>’s fetcher will give you a plug-and-play solution for live-stream subscriptions into your app’s Graph<em>i</em>QL editor!</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Note that we are still using the original&nbsp;<code>&lt;em&gt;graphQLFetcher&lt;/em&gt;</code>&nbsp;inside the new fetcher. We fall back to the original for GraphQL operations that aren’t subscriptions (queries and mutations).</p></blockquote>



<h2 class="wp-block-heading" id="3f85"><a href="#try-it-today" aria-hidden="true" class="aal_anchor" id="try-it-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>Try it today!</h2>



<p>Even though GraphQL subscriptions are still at the RFC stage, it is already being used by many companies in production, and the libraries and tools have been evolving to support a wide range of use cases. So try GraphQL subscriptions in order to add real time ability to your apps today!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="520" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_tVIRc087V_7VlSs46TwlYQ-1024x520.png" alt="" class="wp-image-1140" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_tVIRc087V_7VlSs46TwlYQ-1024x520.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_tVIRc087V_7VlSs46TwlYQ-300x152.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_tVIRc087V_7VlSs46TwlYQ-768x390.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_tVIRc087V_7VlSs46TwlYQ-1200x609.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_tVIRc087V_7VlSs46TwlYQ.png 1400w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>


How to Use Subscriptions in GraphiQL


<p>Designing a good GraphQL API is tricky, because you always want to balance utility and convenience with a consideration around how the API may evolve in the future.</p>



<p>The main points to consider when designing your GraphQL mutations are:</p>



<ul class="wp-block-list"><li><strong>Naming.</strong>&nbsp;Name your mutations verb first. Then the object, or “noun,” if applicable. Use camelCase.</li><li><strong>Specificity.&nbsp;</strong>Make mutations as&nbsp;<em>specific</em>&nbsp;as possible. Mutations should represent semantic actions that might be taken by the user whenever possible.</li><li><strong>Input object.&nbsp;</strong>Use a single, required, unique, input object type as an argument for easier mutation execution on the client.</li><li><strong>Unique payload type.&nbsp;</strong>Use a unique payload type for each mutation and add the mutation’s output as a field to that payload type.</li><li><strong>Nesting.&nbsp;</strong>Use nesting to your advantage wherever it makes sense.</li></ul>



<p>This article will explain the rationale behind each of these points and equip you to design an effective GraphQL mutation system for your API.</p>



<h2 class="wp-block-heading" id="f480"><a href="#picking-a-name-for-your-mutation" aria-hidden="true" class="aal_anchor" id="picking-a-name-for-your-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>Picking a name for your mutation</h2>



<p>In short, try to name your mutation verb first. Your mutation represents an&nbsp;<em>action</em>&nbsp;so start with an action word that best describes what the mutation does.</p>



<p>Names like&nbsp;<code>createUser</code>,&nbsp;<code>likePost</code>,&nbsp;<code>updateComment</code>, and&nbsp;<code>reloadUserFeed</code>&nbsp;are preferable to names like&nbsp;<code>userCreate</code>,&nbsp;<code>postLike</code>,&nbsp;<code>commentUpdate</code>, and&nbsp;<code>userFeedReload</code>.</p>



<p>Some teams, like the GraphQL team at&nbsp;<a href="https://youtu.be/Wlu_PWCjc6Y?t=11m58s" target="_blank" rel="noreferrer noopener">Shopify</a>, prefer to write names the other way around —&nbsp;<code>userCreate</code>&nbsp;over&nbsp;<code>createUser</code>. This is useful for schemas where you want to order the mutations alphabetically (the Ruby GraphQL gem always orders fields alphabetically) and your data model is mostly object-oriented with CRUD methods (create, read, update, and delete). When all your mutations are centered around a handful of object types this convention makes sense.</p>



<p>However, many applications have mutations that do not map directly to actions that can be performed on objects in your data model. For instance, say you were building a password reset feature into your app. To actually send that email you may have a mutation named:&nbsp;<code>sendPasswordResetEmail</code>. This mutation is more like an RPC call then a simple CRUD action on a data type.</p>



<p>The password reset email case is also a good use case for illustrating why you want specific mutations over general mutations. You may be tempted to create a mutation like&nbsp;<code>sendEmail(type: PASSWORD_RESET)</code>&nbsp;and call this mutation with all the different email types you may have. This is not a good design because it will be much more difficult to enforce the correct input in the GraphQL type system and understand what operations are available in GraphiQL. For example, in the future you might want to send a new input argument with one of your emails. If you start with a general “catch-all” mutation, adding extra inputs is much more difficult.</p>



<p>Don’t be afraid of super specific mutations that correspond exactly to an update that your UI can make.&nbsp;<strong>Specific mutations that correspond to semantic user actions are more powerful than general mutations</strong><strong>.</strong>&nbsp;This is because specific mutations are easier for a UI developer to write, they can be optimized by a backend developer, and only providing a specific subset of mutations makes it much harder for an attacker to exploit your API.</p>



<p>Naming conventions vary on a team-by-team basis. If you want to pick a different naming convention that’s fine, but stick to it! The above suggestion is the naming convention that I find works best for the largest range of use cases.</p>



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



<p>Mutations should only ever have one input argument. That argument should be named&nbsp;<code>input</code>&nbsp;and should have a non-null&nbsp;<em>unique&nbsp;</em>input object type. In other words, your mutations should look like:</p>



<pre class="wp-block-preformatted">updatePost(input: { id: 4, newText: "..." }) { ... }</pre>



<p>Instead of:</p>



<pre class="wp-block-preformatted">updatePost(id: 4, newText: "...") { ... }</pre>



<p>But why? The reason is that the first style is much easier to use client-side. The client is only required to send one variable with per mutation instead of one for every argument on the mutation.</p>



<p>This seems like a small difference, but when you have mutations that need 10+ arguments your mutation GraphQL file will become much smaller.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">mutation MyMutation($input: UpdatePostInput!) {
  updatePost(input: $input) { ... }
}

# vs.

mutation MyMutation($id: ID!, $newText: String, ...) {
  updatePost(id: $id, newText: $newText, ...) { ... }
}</code></pre>



<p>The next thing you should do is nest the input object as much as possible. In GraphQL schema design nesting is a virtue. For no cost besides a few extra keystrokes, nesting allows you to fully embrace GraphQL’s power to be your version-less API. Nesting gives you room on your object types to explore new schema designs as time goes on. You can easily deprecate sections of the API and add new names in a conflict free space instead of fighting to find a new name on a cluttered collision-rich object type.</p>



<p>Think of nesting as an investment into the future of your API. See the following for an example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation {
  createPerson(input: {
    # By nesting we have room at the top level of `input`
    # to add fields like `password`, or metadata fields like
    # `clientMutationId` for Relay. We could also deprecate
    # `person` in the future to use another top level field
    # like `partialPerson`.
    password: &quot;qwerty&quot;
    person: {
      id: 4
      name: &quot;Budd Deey&quot;
    }
  }) { ... }
  updatePerson(input: {
    # The `id` field represents who we want to update.
    id: 4
    # The `patch` field represents what we want to update.
    patch: {
      name: &quot;Budd Deey&quot;
    }
  }) { ... }
}</code></pre>



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



<p>Just like when you design your input, nesting is a virtue for your GraphQL payload. Always create a custom object type for each of your mutations and then add any output you want as a field of that custom object type. This will allow you to add multiple outputs over time and metadata fields like <code>clientMutationId</code> or <code>userErrors</code>. Just like with inputs nesting is an investment that will pay off.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation {
  createPerson(input: { ... }) {
    # You could add other fields now to your mutation payload.
    # Like `clientMutationId` or `userErrors`.
    person {
      id
      name
    }
  }
  updatePerson(input: { ... }) {
    person {
      id
      name
    }
  }
}</code></pre>



<p>Even if you only want to return a single thing from your mutation, resist the temptation to return that one type directly. It is hard to predict the future, and if you choose to return only a single type now you remove the future possibility to add other return types or metadata to the mutation. Preemptively removing design space is not something you want to do when designing a versionless GraphQL API.</p>



<h2 class="wp-block-heading" id="c6cd"><a href="#putting-it-all-together" aria-hidden="true" class="aal_anchor" id="putting-it-all-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 all together.</h2>



<p>Here is an example of a well-structured GraphQL mutation system for a TodoMVC application using the suggestions provided in this article.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Todo {
  id: ID!
  text: String
  completed: Boolean
}

schema {
  # The query types are omitted so we can focus on the mutations!
  mutation: RootMutation
}

type RootMutation {
  createTodo(input: CreateTodoInput!): CreateTodoPayload
  toggleTodoCompleted(input: ToggleTodoCompletedInput!): ToggleTodoCompletedPayload
  updateTodoText(input: UpdateTodoTextInput!): UpdateTodoTextPayload
  completeAllTodos(input: CompleteAllTodosInput!): CompleteAllTodosPayload
}

# `id` is generated by the backend, and `completed` is automatically
# set to false.
input CreateTodoInput {
  # I would nest, but there is only one field: `text`. It would not
  # be hard to make `text` nullable and deprecate the `text` field,
  # however, if in the future we decide we have more fields.
  text: String!
}

type CreateTodoPayload {
  # The todo that was created. It is nullable so that if there is
  # an error then null won’t propagate past the `todo`.
  todo: Todo
}

# We only accept the `id` and the backend will determine the new
# `completed` state of the todo. This prevents edge-cases like:
# “set the todo’s completed status to true when its completed
# status is already true” in the type system!
input ToggleTodoCompletedInput {
  id: ID!
}

type ToggleTodoCompletedPayload {
  # The updated todo. Nullable for the same reason as before.
  todo: Todo
}

# This is a specific update mutation instead of a general one, so I
# don’t nest with a `patch` field like I demonstrated earlier.
# Instead I just provide one field, `newText`, which signals intent.
input UpdateTodoTextInput {
  id: ID!
  newText: String!
}

type UpdateTodoTextPayload {
  # The updated todo. Nullable for the same reason as before.
  todo: Todo
}

input CompleteAllTodosInput {
  # This mutation does not need any fields, but we have the space for
  # input anyway in case we need it in the future.
}

type CompleteAllTodosPayload {
  # All of the todos we completed.
  todos: [Todo]
  # If we decide that in the future we want to use connections we may
  # also add a `todoConnection` field.
}</code></pre>



<h3 class="wp-block-heading" id="b84c"><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</h3>



<p>With these design principles you should be equipped to design an effective GraphQL mutation system for your API.</p>



<p>This article represents how I currently think about designing mutations for GraphQL APIs as informed by my experience working on several kinds of projects. There were teams where the API was pre-designed for me, projects where I built a custom API, my work on&nbsp;<a href="https://github.com/postgraphql/postgraphql" target="_blank" rel="noreferrer noopener">PostGraphQL</a>&nbsp;designing a general purpose GraphQL API for anyone, and conversations with Facebook and other production GraphQL users. These design principles also take heavy inspiration from the&nbsp;<a href="http://facebook.github.io/relay/graphql/mutations.htm" target="_blank" rel="noreferrer noopener">Relay Input Object Mutations Specification</a>.</p>



<p>If you want a deep technical understanding of how mutations work in GraphQL, I’m working on an upcoming article titled “Understanding GraphQL Mutations”, coming soon to this blog.</p>



<p>If you have a different opinion on how mutations should be designed, that’s fine, and I want to hear it! Just know that it is important to always plan for the future when designing your mutations and any other part of your GraphQL API.</p>


Designing GraphQL Mutations

React + GraphQL Tutorial — The Server

Full-stack React + GraphQL Tutorial


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This is a guest post by&nbsp;<a href="https://medium.com/u/72347b4464b3?source=post_page-----f8b86d7f5297----------------------" target="_blank" rel="noreferrer noopener">Nikolas Burk</a>, who works on iOS and GraphQL education at&nbsp;<a href="https://www.graph.cool/" target="_blank" rel="noreferrer noopener">Graphcool</a>, an awesome GraphQL backend platform.</p></blockquote>



<p><a href="https://www.learnapollo.com/" target="_blank" rel="noreferrer noopener">Learn Apollo</a>&nbsp;is an interactive tutorial that explains how to develop applications using a&nbsp;<a href="http://graphql.org/" target="_blank" rel="noreferrer noopener">GraphQL</a>&nbsp;backend and&nbsp;<a href="http://dev.apollodata.com/" target="_blank" rel="noreferrer noopener">Apollo</a>&nbsp;client. It’s the fastest way to get started with Apollo &amp; GraphQL, guiding you through practical examples using the client technology of your choice — be it&nbsp;<strong>React, React Native, Angular or Vue</strong>.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><em>Note: If you have never heard of&nbsp;</em><a href="http://graphql.org/" target="_blank" rel="noreferrer noopener"><em>GraphQL</em></a><em>&nbsp;before, it’s an API design paradigm that was&nbsp;</em><a href="http://graphql.org/blog/graphql-a-query-language" target="_blank" rel="noreferrer noopener"><em>introduced by Facebook</em></a><em>&nbsp;and eliminates many shortcomings of today’s de-facto standard REST.&nbsp;</em><a href="http://dev.apollodata.com/" target="_blank" rel="noreferrer noopener"><em>Apollo</em></a><em>&nbsp;is a&nbsp;</em>client-side data fetching library<em>&nbsp;that allows you to easily work with a GraphQL API and benefit from built-in features like caching, subscriptions, optimistic UI, pagination and server-side rendering without the overhead of implementing these yourself!</em></p></blockquote>



<p>After the&nbsp;<a href="https://dev-blog.apollodata.com/learn-apollo-build-graphql-apps-with-react-react-native-or-exponent-4787269a4747#.x7cyjvpq9" target="_blank" rel="noreferrer noopener">successful launch</a>&nbsp;of Learn Apollo for React &amp; React Native, we’re happy to introduce the&nbsp;<strong>iOS track</strong>&nbsp;for&nbsp;<a href="https://www.learnapollo.com/" target="_blank" rel="noreferrer noopener">Learn Apollo</a>. Similar to the other tracks you can find on the site, the goal is to build a fully-fledged Pokédex application that demonstrates major functionalities of the interaction with a GraphQL backend using an Apollo client —&nbsp;<strong>only this time it’s from within an iOS app using Swift!</strong>&nbsp;🚀</p>



<h2 class="wp-block-heading" id="381b"><a href="#the-apollo-ios-client" aria-hidden="true" class="aal_anchor" id="the-apollo-ios-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>The Apollo iOS client</h2>



<p>The&nbsp;<a href="https://github.com/apollostack/apollo-ios" target="_blank" rel="noreferrer noopener">Apollo iOS Client</a>&nbsp;is the best way to work with a GraphQL API from a native iOS app. Developers using the client will benefit from two major features:</p>



<ul class="wp-block-list"><li><strong>Type generation based on GraphQL queries and mutations</strong></li><li><strong>Normalized cache &amp; automatic UI updates</strong></li></ul>



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



<p>The first and presumably most important feature of the Apollo iOS client is the&nbsp;<a href="https://dev-blog.apollodata.com/mapping-graphql-types-to-swift-aa85e5693db4#.tjm7h9e8q" target="_blank" rel="noreferrer noopener">generation of native Swift types</a>&nbsp;that reflect the data requirements of your specific application. The types are generated based on all the queries and mutations that are specified within the app’s Xcode project.</p>



<p>This approach leverages Swift’s static type system and, unlike most other data fetching approaches, provides&nbsp;<em>compile-time safety&nbsp;</em>for the developer in terms of what data they can expect from the backend. In Swift, this means that developers can get rid of all the&nbsp;<em>optional</em>&nbsp;properties they’d have to use when parsing the untyped JSON into their model objects, thus providing extra safety while retaining flexibility when it comes to changing data requirements.</p>



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



<p>The second major feature of the Apollo iOS client is a&nbsp;<a href="http://dev.apollodata.com/ios/watching-queries.html" target="_blank" rel="noreferrer noopener">normalized cache</a>&nbsp;that allows for automatic UI updates. The responses that the client receives from the server are flattened and put into the client-side store. Similar to the Apollo client for other platforms, queries are&nbsp;<a href="http://dev.apollodata.com/ios/watching-queries.html" target="_blank" rel="noreferrer noopener"><em>watched</em></a>&nbsp;in a reactive way so that an update function automatically gets executed whenever data associated with a watched query changes in the store — no matter where that change came from!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="259" height="480" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_6-oRuAkgYyiHSB_-kJXIGg.gif" alt="" class="wp-image-530"/><figcaption>Throughout the tutorial you’ll build a fully-functional iOS app with GraphQL &amp; Apollo</figcaption></figure>



<h2 class="wp-block-heading" id="b063"><a href="#why-should-an-ios-developer-care-about-graphql" aria-hidden="true" class="aal_anchor" id="why-should-an-ios-developer-care-about-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>Why should an iOS developer care about GraphQL?</h2>



<p>At&nbsp;<a href="https://www.graph.cool/" target="_blank" rel="noreferrer noopener">Graphcool</a>, we strongly believe that&nbsp;<strong>GraphQL is the API design paradigm of the future</strong>! Despite its young age, it already created an incredible impact on the way how web developers write their applications and interface with backends.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><em>“We were frustrated with the differences between the data we wanted to use in our apps and the server queries they required. We don’t think of data in terms of resource URLs, secondary keys, or join tables; we think about it in terms of a graph of objects and the models we ultimately use in our apps like NSObjects or JSON.” —&nbsp;</em><a href="https://twitter.com/leeb" target="_blank" rel="noreferrer noopener"><em>Lee Byron</em></a><em>&nbsp;(Co-Inventor of GraphQL, Facebook)</em></p></blockquote>



<p>Though GraphQL has been widely adopted in the web development community so far, Facebook initially developed it to deal with networking issues they primarily saw on&nbsp;<em>mobile devices</em>&nbsp;— with the&nbsp;<a href="http://graphql.org/blog/graphql-a-query-language/#why-graphql" target="_blank" rel="noreferrer noopener">goal of making the data transfer as efficient as possible</a>&nbsp;while still enabling developers to iterate quickly. This is why we think that there is an&nbsp;<strong>enormous potential for GraphQL in the native mobile development space</strong>! We’re very excited to see more mobile developers using GraphQL, and want to build an ecosystem that makes it as easy as possible for every native developer to integrate GraphQL in their applications.</p>


How to use GraphQL in your iOS app


<p>One of the main goals of&nbsp;<a href="http://dev.apollodata.com/" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;and the Apollo project in general is to fit seamlessly into the modern React developer’s toolbox. That’s why we’ve invested in simple&nbsp;<a href="https://dev-blog.apollodata.com/seamless-integration-for-graphql-and-react-6ffc0ad3fead#.h3dquahg5" target="_blank" rel="noreferrer noopener">higher-order components</a>,&nbsp;<a href="http://dev.apollodata.com/react/server-side-rendering.html" target="_blank" rel="noreferrer noopener">server-side rendering</a>, and&nbsp;<a href="http://dev.apollodata.com/react/react-native.html" target="_blank" rel="noreferrer noopener">React Native</a>.</p>



<p>Increasingly, React developers are working more and more with small, focused components, and the&nbsp;<a href="https://github.com/acdlite/recompose" target="_blank" rel="noreferrer noopener">Recompose</a>&nbsp;library by&nbsp;<a href="https://medium.com/u/6025bd347b9a?source=post_page-----8b9e302dea51----------------------" target="_blank" rel="noreferrer noopener">Andrew Clark</a>&nbsp;takes that to the next level. When Andrew&nbsp;<a href="https://www.youtube.com/watch?v=zD_judE-bXk" target="_blank" rel="noreferrer noopener">presented it at React Europe last year</a>, he referred to it as a toolbox like Underscore or Lodash, but for React components. Here are some things you can do with Recompose:</p>



<ul class="wp-block-list"><li>Optimize your React components by making them pure-rendered</li><li>Set default props</li><li>Add limited state variables</li></ul>



<p>And you can do all of this while using the&nbsp;<a href="https://facebook.github.io/react/docs/components-and-props.html#functional-and-class-components" target="_blank" rel="noreferrer noopener">React functional component syntax</a>, which makes your code much more straightforward and reduces your chances of accidentally introducing some state or complexity into your UI rendering.</p>



<p>The React higher order component you use from&nbsp;<code>react-apollo</code>&nbsp;fits this mold. It just does one thing well: It enables you to co-locate your GraphQL query with your React component and get that data in your&nbsp;<code>props</code>, while handling all of the details like fetching and caching the data. It doesn’t do anything else, like manage variable state. That’s where React component composition and Recompose come in.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="363" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-1024x363.png" alt="" class="wp-image-527" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-1024x363.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-300x106.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-768x272.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-1536x544.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-2048x726.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-1200x425.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-5OaljKSRCfHxtThFZIFhQ-1980x702.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>We can attach GraphQL data, loading management, variable state, or pure rendering in just one function call!</figcaption></figure>



<p>Without further ado, here is our first end-to-end example of how to use Recompose together with React Apollo to have a nice, concise UI with GraphQL!</p>



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



<p>The best feature of functional components is that they are stateless. This means for a certain set of props you will always get the same output, making the component predictable and easy to test. However, sometimes you still want some temporary state, and it’s best to put that outside of the component that handles rendering to keep things clean.</p>



<p>Let’s look how we can use the <code>withState</code> container from Recompose to build a React component that has both a search box and a GraphQL query that uses that search term:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import React from &#039;react&#039;;
import { withState, pure, compose } from &#039;recompose&#039;;
import gql from &#039;graphql-tag&#039;;
import { graphql } from &#039;react-apollo&#039;;
import { Link } from &#039;react-router&#039;;

// The data prop, which is provided by the wrapper below, contains
// a `loading` key while the query is in flight, and the bookSearch
// results when they are ready
const BookSearchResultsPure = ({ data: { loading, bookSearch } }) =&gt; {
  if (loading) {
    return &lt;div&gt;Loading&lt;/div&gt;;
  } else {
    return (
      &lt;ul&gt;
        {bookSearch.map(book =&gt;
          &lt;li key={book.id}&gt;
            &lt;Link to={`/details/${book.id}`}&gt;
              {book.title} by {book.author.name}
            &lt;/Link&gt;
          &lt;/li&gt;
        )}
      &lt;/ul&gt;
    );
  }
};

// The `graphql` wrapper executes a GraphQL query and makes the results
// available on the `data` prop of the wrapped component.
//
// Note that if you type a search field and then hit backspace, the
// Apollo cache kicks in and no actual data loading is done.
const data = graphql(gql`
  query BookSearchQuery($keyword: String!) {
    bookSearch(keyword: $keyword) {
      id
      image
      title
      author {
        id
        name
      }
    }
  }
`, {
  // The variable $keyword for the query is computed from the
  // React props passed to this container.
  options: (props) =&gt; ({
    variables: { keyword: props.keyword },
  }),
});

// Attach the data HoC to the pure component
const BookSearchResults = compose(
  data,
  pure,
)(BookSearchResultsPure);

// Use recompose to keep the state of the input so that we
// can use functional component syntax
const keyword = withState(&#039;keyword&#039;, &#039;setKeyword&#039;, &#039;&#039;);

const BookSearchPure = ({ keyword, setKeyword }) =&gt; (
  &lt;div&gt;
    &lt;input
      type=&quot;text&quot;
      value={ keyword }
      onChange={(e) =&gt; setKeyword(e.target.value)}
    /&gt;

    &lt;BookSearchResults keyword={keyword} /&gt;
  &lt;/div&gt;
);

// Attach the state to the pure component
const BookSearch = compose(
  keyword,
  pure,
)(BookSearchPure);

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



<p>One nice side effect is that since we are keeping all of the state and data loading outside of the component, we can drop in the&nbsp;<code>pure</code>&nbsp;mix-in everywhere to make sure our components don’t rerender when they don’t need to.</p>



<p>In the above code snippet, all of our concerns are very nicely separated through the React component paradigm. We have two components for rendering HTML, one for keeping track of the search box state, and one for data loading. We can test and inspect each one separately.</p>



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



<p>One thing that’s not so nice about the <code>BookSearchResultsPure</code> component above is that it has an if statement with multiple returns. This means you have to interpret that logic in your mind to see what the result might look like. We could also use an HoC to flatten this out:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import React from &#039;react&#039;;
import { pure, branch, renderComponent, compose } from &#039;recompose&#039;;
import gql from &#039;graphql-tag&#039;;
import { graphql } from &#039;react-apollo&#039;;
import { Link } from &#039;react-router&#039;;

// Define a very basic loading state component - you could make this
// a nice animation or something
const Loading = () =&gt; (
  &lt;div&gt;Loading&lt;/div&gt;
);

// Define an HoC that displays the Loading component instead of the
// wrapped component when props.data.loading is true
const displayLoadingState = branch(
  (props) =&gt; props.data.loading,
  renderComponent(Loading),
);

// The pure component that renders UI
const BookSearchResultsPure = ({ data: { bookSearch } }) =&gt; (
  &lt;ul&gt;
    {bookSearch.map(book =&gt;
      &lt;li key={book.id}&gt;
        &lt;Link to={`/details/${book.id}`}&gt;
          {book.title} by {book.author.name}
        &lt;/Link&gt;
      &lt;/li&gt;
    )}
  &lt;/ul&gt;
);

// The GraphQL query wrapper, provides a data prop with a loading
// field on it
const data = graphql(gql`
  query BookSearchQuery($keyword: String!) {
    ...
  }
`, {
  options: ({ keyword }) =&gt; ({ variables: { keyword } }),
});

// Put everything together!
const BookSearchResults = compose(
  data,
  displayLoadingState,
  pure,
)(BookSearchResultsPure);</code></pre>



<p>Now, we can very easily share a common&nbsp;<code>loading</code>&nbsp;component between all of our UI that uses data from React-Apollo, and the logic is contained in a separate chunk that isn’t obscuring the structure of our pure component!</p>



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



<p>The&nbsp;<code>react-apollo</code>&nbsp;API was designed to be the best way to pull GraphQL data into the props of a React component. Combined with a library like Recompose, it gives you an incredibly powerful and flexible way to declaratively connect server-side data to your react components while keeping them pure.</p>



<p><a href="https://medium.com/u/6d7ee7c0b225?source=post_page-----8b9e302dea51----------------------" target="_blank" rel="noreferrer noopener">Abhi Aiyer&nbsp;</a>has already written a great follow-up about how to use Recompose to work nicely with mutations:<a href="https://medium.com/front-end-developers/how-i-write-mutations-in-apollo-w-recompose-1c0ab06ef4ea" target="_blank" rel="noreferrer noopener">How I write Mutations in Apollo w/ RecomposeSince Sashko Stubailo launched his post about Apollo + Recompose, which is a great blog post by the way, I wanted to show everyone how I…medium.com</a></p>



<p>Thanks Abhi! And if anyone else has great ideas about how to use Apollo and Recompose together, please let me know in the responses!</p>



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



<p><em>Want to work full-time on GraphQL technology, collaborate with the open source community, and write articles like these? We’re actively hiring for a variety of positions!&nbsp;</em><a href="http://jobs.meteor.com/" target="_blank" rel="noreferrer noopener"><em>Check them out.</em></a></p>


Simplify your React components with Apollo and Recompose


<p>When building a GraphQL application, there are benefits that come from placing your GraphQL query documents in their own files rather than inline with your view components. For example, you can get simpler editor and tooling support since the tools can look at static files instead of trying to parse application code. Also, it prevents you from&nbsp;<a href="https://dev-blog.apollodata.com/5-benefits-of-static-graphql-queries-b7fa90b0b69a#.9okwzr2dn" target="_blank" rel="noreferrer noopener">accidentally manipulating queries at runtime</a>. However, until now it has been difficult to do with our GraphQL webpack loader since there was no way to have different queries share GraphQL fragments.</p>



<p>This is a short post that describes one of the features we recently built into our Webpack loader for GraphQL documents —&nbsp;<a href="https://github.com/apollostack/graphql-tag" target="_blank" rel="noreferrer noopener">graphql-ta</a>g — that solves this problem.</p>



<p>Until now, the loader only gave you the ability to load a query from a single file, but with a recent update you can now import fragment definitions from other&nbsp;<code>.graphql</code>&nbsp;files. This makes it easy to place GraphQL documents outside of your view component definitions and share fragments across those documents. Now that the support for these files is fully featured, you can easily take advantage of built-in editor code highlighting for&nbsp;<code>.graphql</code>&nbsp;files, for example on GitHub:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="729" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-1024x729.png" alt="" class="wp-image-487" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-1024x729.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-300x214.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-768x547.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-1536x1094.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-1200x855.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg-1980x1410.png 1980w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_w64zULCm_M_1lXhjrDmbGg.png 2016w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>That sweet, sweet highlighting.</figcaption></figure>



<h2 class="wp-block-heading" id="2b42"><a href="#using-it" aria-hidden="true" class="aal_anchor" id="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>Using it</h2>



<p>Right now, most Apollo Client apps are written by putting queries inside JavaScript template literals with a&nbsp;<code>gql</code>&nbsp;tag:</p>



<pre class="wp-block-preformatted">export const COMMENT_QUERY = gql`<br>  query Comment($repoName: String!) {<br>    …<br>  }<br>}`;const withData = graphql(COMMENT_QUERY, {<br> // options<br>});</pre>



<p>This is a reasonable approach. But, if we don’t want to place our queries inline with our React components, we can do that with&nbsp;<code>graphql-tag/loader.</code>To start using it, we edit the Webpack config so that it looks like this:</p>



<pre class="wp-block-preformatted">module.exports = {<br>  …<br>  module: {<br>    loaders: [{<br>      test: /\.(graphql|gql)$/,<br>      exclude: /node_modules/,<br>      loader: ‘graphql-tag/loader’<br>    }]<br>   },<br>  …<br>}</pre>



<p>Now, we can place our query document in a file called&nbsp;<code>CommentQuery.graphql,</code>&nbsp;and then import it within our Javascript code:</p>



<pre class="wp-block-preformatted">import COMMENT_QUERY from '../graphql/CommentQuery.graphql';</pre>



<p>When the bundle is created, Webpack will load the&nbsp;<code>.graphql</code>&nbsp;file and use the GraphQL parser in order to set&nbsp;<code>COMMENT_QUERY</code>&nbsp;to a parsed version of the query contained within the&nbsp;<code>.graphql</code>&nbsp;file. Now, let’s say that this query used a fragment spread internally:</p>



<pre class="wp-block-preformatted">query Comment($repoName: String!) {<br>  …<br>  ...CommentsPageComment<br>  …<br>}fragment CommentsPageComment {<br>  …<br>} </pre>



<p>We could put both the query definition and the fragment definition in the same file. But, if the fragment is shared across multiple queries, we’d have to define it with every query that used. Instead, we can use&nbsp;<code>graphql-tag/loader</code>’s preprocessor&nbsp;<code>#import</code>&nbsp;statement. This is what our query file would look like:</p>



<pre class="wp-block-preformatted">#import "./CommentsPageComment.graphql"query Comment($repoName: String!) {<br> …<br> ...CommentsPageComment<br> …<br>}</pre>



<p>and the file&nbsp;<code>CommentsPageComment.graphql</code>&nbsp;would contain:</p>



<pre class="wp-block-preformatted">fragment CommentsPageComment on Comment {<br>  id<br>  postedBy {<br>    login<br>    html_url<br>  }<br>  createdAt<br>  content<br>}</pre>



<p>This allows us to import&nbsp;<code>COMMENT_QUERY</code>&nbsp;as we did previously without worrying about having to import the fragment separately within our Javascript code.</p>



<p>That’s all you need to understand to start using&nbsp;<code>graphql-tag/loader</code>&nbsp;in your projects. If you’d like to see an example, you can check out how we use&nbsp;<code>.graphql</code>&nbsp;files and preprocessor&nbsp;<code>#import</code>&nbsp;statements within our example app,&nbsp;<a href="https://github.com/apollostack/GitHunt-React" target="_blank" rel="noreferrer noopener">GitHunt-React</a>.</p>



<h2 class="wp-block-heading" id="586d"><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 implementation of&nbsp;<code>graphql-tag/loader</code>&nbsp;is incredibly simple. Since it is a Webpack loader, it has to turn each&nbsp;<code>.graphql</code>&nbsp;into a bit of Javascript code that Webpack can place into the bundle it creates. Let’s consider what happens when we try to import this file:</p>



<pre class="wp-block-preformatted">#import "./CommentsPageComment.graphql"query Comment($repoName: String!) {<br> …<br> ...CommentsPageComment<br> …<br>}</pre>



<p>Notice that the first line is a GraphQL comment. This means that to an ordinary GraphQL parser, the import statement would be ignored entirely. But,&nbsp;<code>graphql-tag/loader</code>&nbsp;will process it and replace it with a&nbsp;<code>require</code>&nbsp;statement in the outputted code. It will then parse the whole document contained in this file and combine it with the definitions in the imported file. The Javascript code that&nbsp;<code>graphql-tag/loader</code>&nbsp;outputs should look like this:</p>



<pre class="wp-block-preformatted">var doc = // JSON object that represents the parsed GraphQL document<br>doc.definitions = doc.definitions<br>  .concat(<br>    require('CommentsPageComment.graphql').definitions<br>  );<br>module.exports = doc;</pre>



<p>Notice that with the&nbsp;<code>require</code>&nbsp;statement,&nbsp;<code>graphql-tag/loader</code>&nbsp;will be executed again on&nbsp;<code>CommentsPageComment.graphql</code>&nbsp;by Webpack. This makes it possible to have&nbsp;<code>#import</code>&nbsp;statements within that file too. By generating this Javascript code, the loader makes it possible to import your&nbsp;<code>.graphql</code>&nbsp;files from your Javascript code.</p>



<h2 class="wp-block-heading" id="5df7"><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>Importing files that contain static queries makes it possible to&nbsp;<a href="https://dev-blog.apollodata.com/5-benefits-of-static-graphql-queries-b7fa90b0b69a#.tu5h811jv" target="_blank" rel="noreferrer noopener">build all kinds of neat tools</a>, including support for persisted queries. We’ve actually built support for persisted queries on top of this improved Webpack loader, and we’ll have a blog post explaining how to use them soon!</p>


Webpack’ing your GraphQL Documents


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This is a guest post by&nbsp;<a href="https://www.graph.cool/" target="_blank" rel="noreferrer noopener">Graphcool</a>&nbsp;founder&nbsp;<a href="https://twitter.com/_schickling" target="_blank" rel="noreferrer noopener">Johannes Schickling</a>, who is working on making an awesome GraphQL backend platform, as well as community resources and events.</p></blockquote>



<p>GraphQL is a massive paradigm shift in software development defining a new standard for client-server communication. Apollo Client is the easiest way to use GraphQL for your own frontend applications.</p>



<p>To make it even easier possible to get started with Apollo, we’re thrilled to announce <a rel="noreferrer noopener" href="https://www.graph.cool/" target="_blank">Graphcool</a>’s newest community project: <a rel="noreferrer noopener" href="https://www.learnapollo.com/" target="_blank"><strong>Learn Apollo</strong></a><strong>.</strong></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="Learn Apollo - Introduction" width="580" height="435" src="https://www.youtube.com/embed/UNoHVLrItXQ?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="8377"><a href="#a-hands-on-tutorial-for-apollo-graphql-client" aria-hidden="true" class="aal_anchor" id="a-hands-on-tutorial-for-apollo-graphql-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>A hands-on tutorial for Apollo GraphQL Client</h2>



<p>Learn Apollo is an interactive tutorial introducing all Apollo’s core concepts. Step by step, you will build a fully-fledged application guided by practical examples. By the end of this tutorial you’ll be ready to build your own apps with Apollo.</p>



<p><em>Note: Learn Apollo is not meant as a replacement for the&nbsp;</em><a href="http://dev.apollodata.com/" target="_blank" rel="noreferrer noopener"><em>Apollo documentation</em></a><em>&nbsp;but as an easier entry point to get started.</em></p>



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



<p>Apollo can be used with many different frameworks, so when you start the tutorial we ask you to pick the&nbsp;<em>track</em>&nbsp;you want to follow. As of today you can choose React, React Native or Exponent, and we are already working on tracks for Angular and Vue.js.</p>



<p>Each track comes prepared with a example codebase (a Pokedex app) which you’ll extend throughout the tutorial as new concepts are introduced.</p>



<figure class="wp-block-image size-large"><a href="https://demo.learnapollo.com/"><img loading="lazy" decoding="async" width="668" height="526" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_-elBh3BgQnldU4YYgr2DTg.gif" alt="" class="wp-image-469"/></a><figcaption>We’re providing the UI and structure of the Pokedex app, so you can focus on learning Apollo</figcaption></figure>



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



<p>To help you focus entirely on using Apollo in a frontend application, we’ve included a pre-configured GraphQL backend endpoint which works out of the box with every example app. Your backend can be accessed via GraphiQL or the integrated data browser. All you need to do is to authenticate with Github to get your personal GraphQL endpoint.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="478" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_4391sUODacK3eDkmW_aWbA-1024x478.gif" alt="" class="wp-image-470" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_4391sUODacK3eDkmW_aWbA-1024x478.gif 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4391sUODacK3eDkmW_aWbA-300x140.gif 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_4391sUODacK3eDkmW_aWbA-768x358.gif 768w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>After authenticating via Github you’ll get a pre-configured GraphQL endpoint</figcaption></figure>



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



<p>After the&nbsp;<a href="https://twitter.com/LearnRelay/status/786639860744482816" target="_blank" rel="noreferrer noopener">successful launch of Learn Relay</a>&nbsp;we’re now applying the same tutorial format to other great technologies. Learn Apollo is made possible by great contributions from our amazing community. The entire tutorial and all its resources are open source and&nbsp;<a href="https://github.com/learnapollo" target="_blank" rel="noreferrer noopener">available on Github</a>.</p>



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



<p>To make Learn Apollo as useful as possible, we are looking forward to create tracks for all major technologies making Apollo as approachable as possible for all frontend developers.</p>



<p>If your favorite technology (Angular, Vue, iOS, Android…) is not covered yet, please go ahead and&nbsp;<a href="https://github.com/learnapollo/learnapollo/issues/new" target="_blank" rel="noreferrer noopener">request a new track by filing an issue</a>. Also, if you have any feedback or suggestions on how to improve Learn Apollo, please&nbsp;<a href="https://github.com/learnapollo/learnapollo/issues/new" target="_blank" rel="noreferrer noopener">create an issue here</a>.</p>



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



<p>We couldn’t have done Learn Apollo on our own, so a big thank you to everybody involved:&nbsp;<a href="https://medium.com/u/1d2c02c75335?source=post_page-----4787269a4747----------------------" target="_blank" rel="noreferrer noopener">Tycho Tatitscheff</a>,&nbsp;<a href="https://medium.com/u/b4a7cffadc02?source=post_page-----4787269a4747----------------------" target="_blank" rel="noreferrer noopener">Nilan Marktanner</a>,&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----4787269a4747----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>,&nbsp;<a href="https://medium.com/u/14d61b8e085c?source=post_page-----4787269a4747----------------------" target="_blank" rel="noreferrer noopener">Julian Tapales Maxwell</a>,&nbsp;<a href="https://medium.com/u/53d22f80f3b5?source=post_page-----4787269a4747----------------------" target="_blank" rel="noreferrer noopener">Julian Bauer</a>&nbsp;and&nbsp;<a href="https://medium.com/u/ff75ba3095a6?source=post_page-----4787269a4747----------------------" target="_blank" rel="noreferrer noopener">Johannes Schickling</a>. 🙏</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_eWQHv-S7l7qFa__NTlNN0g-1024x549.png" alt="" class="wp-image-471" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_eWQHv-S7l7qFa__NTlNN0g-1024x549.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_eWQHv-S7l7qFa__NTlNN0g-300x161.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_eWQHv-S7l7qFa__NTlNN0g-768x411.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_eWQHv-S7l7qFa__NTlNN0g.png 1120w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>We hope this tutorial helps you to get started with Apollo quickly in order to use it in your next project. If you have questions about Learn Apollo or need help to get started, let’s&nbsp;<a href="http://slack.graph.cool/" target="_blank" rel="noreferrer noopener">chat</a>. 🙌</p>


Learn Apollo: Build GraphQL Apps with React, React Native or Exponent


<p>GraphQL is a powerful API system based around declaring a schema describing the capabilities of your backend, and then querying that schema with a nice language that projects the data into the shape you want. But that’s just one way to use it. There are so many other uses for the GraphQL query language, especially for cases on the client where importing and running your whole GraphQL schema doesn’t make sense. Enter&nbsp;<a href="https://github.com/apollostack/graphql-anywhere" target="_blank" rel="noreferrer noopener"><em>graphql-anywhere</em></a>, the library that powers&nbsp;<a href="http://dev.apollodata.com/" target="_blank" rel="noreferrer noopener">Apollo Client</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="464" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ-1024x464.png" alt="" class="wp-image-449" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ-1024x464.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ-300x136.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ-768x348.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ-1536x696.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ-1200x543.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_sxMljQ8wgso4cG3PxufTmQ.png 1908w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>As you may recall, writing a GraphQL schema on the server requires you to declare a set of types with fields and resolvers. Since&nbsp;<em>graphql-anywhere</em>&nbsp;doesn’t use a schema, instead you can write just one resolver that is called for every field of the query:</p>



<pre class="wp-block-preformatted">(fieldName, rootValue, args, context, info) =&gt; any</pre>



<p>Then, you can run this resolver with a GraphQL query like so:</p>



<pre class="wp-block-preformatted">import graphql from 'graphql-anywhere'<br><br>graphql(resolver, query)</pre>



<p>It supports all of the features of GraphQL, including fragments, variables, directives, aliases, and more. Read the&nbsp;<a href="https://github.com/apollostack/graphql-anywhere" target="_blank" rel="noreferrer noopener">full docs</a>&nbsp;for all the boring details, but let’s look at some exciting examples!</p>



<h2 class="wp-block-heading" id="e114"><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>It turns out you can do a lot of useful things with a library that traverses GraphQL queries for you.</p>



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



<p>One of the best features of GraphQL is that you only get the data you ask for. Now you can take advantage of this even without a GraphQL server, by writing just two lines of code using <em>graphql-anywhere</em> (all the other lines set up the data):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import gql from &#039;graphql-tag&#039;;
import graphql from &#039;graphql-anywhere&#039;;

// I don&#039;t need all this stuff!
const gitHubAPIResponse = {
  &quot;url&quot;: &quot;https://api.github.com/repos/octocat/Hello-World/issues/1347&quot;,
  &quot;title&quot;: &quot;Found a bug&quot;,
  &quot;body&quot;: &quot;I&#039;m having a problem with this.&quot;,
  &quot;user&quot;: {
    &quot;login&quot;: &quot;octocat&quot;,
    &quot;avatar_url&quot;: &quot;https://github.com/images/error/octocat_happy.gif&quot;,
    &quot;url&quot;: &quot;https://api.github.com/users/octocat&quot;,
  },
  &quot;labels&quot;: [
    {
      &quot;url&quot;: &quot;https://api.github.com/repos/octocat/Hello-World/labels/bug&quot;,
      &quot;name&quot;: &quot;bug&quot;,
      &quot;color&quot;: &quot;f29513&quot;
    }
  ],
};

// Write a query that gets just the fields we want
const query = gql`
  {
    title
    user {
      login
    }
    labels {
      name
    }
  }
`;

// Define a resolver that just returns a property
const resolver = (fieldName, root) =&gt; root[fieldName];

// Filter the data!
const result = graphql(
  resolver,
  query,
  gitHubAPIResponse
);

assert.deepEqual(result, {
  &quot;title&quot;: &quot;Found a bug&quot;,
  &quot;user&quot;: {
    &quot;login&quot;: &quot;octocat&quot;,
  },
  &quot;labels&quot;: [
    {
      &quot;name&quot;: &quot;bug&quot;,
    }
  ],
});</code></pre>



<p>You can also use this feature as part of a utility to filter props for your React components,&nbsp;<a href="http://dev.apollodata.com/react/fragments.html#filtering-with-fragments" target="_blank" rel="noreferrer noopener">as documented here</a>!</p>



<h3 class="wp-block-heading" id="4fa1"><a href="#reading-from-a-redux-store" aria-hidden="true" class="aal_anchor" id="reading-from-a-redux-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>Reading from a Redux store</h3>



<p>If you use&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;already, then your Redux GraphQL data is managed for you. But if you’re using some other method to populate your Redux store and want to use GraphQL just to read from it (perhaps in preparation for getting started with a real GraphQL API on the server), you’ll need something to read that data out of the store and make it match the shape of a GraphQL query. You can use&nbsp;<em>graphql-anywhere</em>&nbsp;for that as well!</p>



<p>Here’s an example of reading from a store generated with the Redux companion <a rel="noreferrer noopener" href="https://github.com/paularmstrong/normalizr" target="_blank">Normalizr</a>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const data = {
  result: [1, 2],
  entities: {
    articles: {
      1: { id: 1, title: &#039;Some Article&#039;, author: 1 },
      2: { id: 2, title: &#039;Other Article&#039;, author: 1 },
    },
    users: {
      1: { id: 1, name: &#039;Dan&#039; },
    },
  },
};

const query = gql`
  {
    result {
      title
      author {
        name
      }
    }
  }
`;

const schema = {
  articles: {
    author: &#039;users&#039;,
  },
};

// This resolver is a bit more complex than others, since it has to
// correctly handle the root object, values by ID, and scalar leafs.
const resolver = (fieldName, rootValue, args, context): any =&gt; {
  if (!rootValue) {
    return context.result.map((id) =&gt; assign({}, context.entities.articles[id], {
      __typename: &#039;articles&#039;,
    }));
  }

  const typename = rootValue.__typename;
  // If this field is a reference according to the schema
  if (typename &amp;&amp; schema[typename] &amp;&amp; schema[typename][fieldName]) {
    // Get the target type, and get it from entities by ID
    const targetType: string = schema[typename][fieldName];
    return assign({}, context.entities[targetType][rootValue[fieldName]], {
      __typename: targetType,
    });
  }

  // This field is just a scalar
  return rootValue[fieldName];
};

const result = graphql(
  resolver,
  query,
  null,
  data // pass data as context since we have to access it all the time
);

// This is the non-normalized data, with only the fields we asked for in our query!
assert.deepEqual(result, {
  result: [
    {
      title: &#039;Some Article&#039;,
      author: {
        name: &#039;Dan&#039;,
      },
    },
    {
      title: &#039;Other Article&#039;,
      author: {
        name: &#039;Dan&#039;,
      },
    },
  ],
});</code></pre>



<p>Depending on the shape of your Redux store, you might need different code in the resolver.</p>



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



<p>If you follow the generally accepted style for writing React code, you probably put prop type declarations on all of your components. Since GraphQL results are deeply nested and sometimes complex, you might end up typing a lot of boilerplate if you want to be explicit about your props. What if you could just use the query you used to get the data as the validator for that prop? Now you can!</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import { propType } from &#039;graphql-anywhere&#039;;

const CommentView = ({ comment }) =&gt; (
  &lt;div&gt;
    &lt;p&gt;{ comment.content }&lt;/p&gt;
    &lt;p&gt;Posted by { comment.postedBy.login } on {comment.createdAt }&lt;/p&gt;
  &lt;/div&gt;
);

CommentView.commentFragment = gql`
  fragment CommentView on Comment {
    id
    postedBy {
      login
    }
    createdAt
    content
  }
`;

CommentView.propTypes = {
  // Works with both queries and fragments!
  comment: propType(CommentView.commentFragment).isRequired,
};

const goodData = {
  id: &#039;asdf&#039;, postedBy: { login: &#039;sashko&#039; },
  createdAt: &#039;2016-12-05T19:32:21+00:00&#039;, content: &#039;I love GraphQL!&#039;,
};

&lt;CommentView comment={goodData} /&gt; // OK

const badData = {
  id: &#039;asdf&#039;,
  createdAt: &#039;2016-12-05T19:32:21+00:00&#039;, content: &#039;I love GraphQL!&#039;,
};

&lt;CommentView comment={badData} /&gt; // PropType error! postedBy missing.</code></pre>



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



<p>So at this point we’ve seen that we can use&nbsp;<em>graphql-anywhere</em>&nbsp;for three things you need to do in almost every app: filtering, denormalization, and argument validation. Since you can use the same GraphQL query or fragment to do all of these things at once, that makes it a pretty convenient technology to work with.</p>



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



<p>The execution process of a query using the&nbsp;<em>graphql-anywhere</em>&nbsp;library is similar to regular GraphQL, except there is no type information and it doesn’t support async data loading (since it’s designed for the client). Basically, the resolver is called once for every field on the query with the arguments provided, and the result from that field is passed into any children as the&nbsp;<em>rootValue</em>.</p>



<p>Because there is no schema involved, we can’t have separate resolvers for different types and fields. Instead, we get the&nbsp;<em>fieldName</em>&nbsp;as an argument, and we can pass down type information in an ad-hoc way through the root value. The first step to designing your&nbsp;<em>graphql-anywhere&nbsp;</em>utility is to ask: what should the root value contain? Since that’s the information passed down to the children, which powers the recursive nature of GraphQL, it’s the core consideration.</p>



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



<p>Want to work on tools like this? Contribute on GitHub or&nbsp;<a href="https://jobs.lever.co/meteor/5e11e6cf-5303-4c12-a3e7-11e5f8da4be1" target="_blank" rel="noreferrer noopener">get a job working on Apollo!</a></p>


Read from Redux, declare PropTypes, and filter data with GraphQL

Navigating your transition to GraphQL

Mapping GraphQL types to Swift


<p>One of the most powerful concepts introduced by Angular 2 is the move to a Component based architecture.</p>



<p>Components are pieces of UI and logic bound together into&nbsp;<strong>reusable</strong>&nbsp;and&nbsp;<strong>self contained</strong>&nbsp;units.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="470" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_-xibJG0BNHwXZxEvOwadIQ-1024x470.png" alt="" class="wp-image-322" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_-xibJG0BNHwXZxEvOwadIQ-1024x470.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-xibJG0BNHwXZxEvOwadIQ-300x138.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-xibJG0BNHwXZxEvOwadIQ-768x352.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_-xibJG0BNHwXZxEvOwadIQ.png 1140w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>Components in Angular 2 and data flow between them</figcaption></figure>



<p>There are two important benefits about Components:</p>



<ol class="wp-block-list"><li>We can&nbsp;<strong>reuse</strong>&nbsp;Components throughout our apps</li><li>When something changes in the inner logic and UI of a Component, it&nbsp;<strong>shouldn’t affect</strong>&nbsp;the other Components outside of it</li></ol>



<p>Those are great benefits, but are they still valid when we start interacting with the server?</p>



<p>I’ll argue in this article that the current way of calling the server with REST API through central Angular services is not a good fit and that co-locating queries with view logic is the natural extension to the component based architecture.</p>



<h2 class="wp-block-heading" id="5c25"><a href="#calling-the-server-with-rest-api-through-central-services" aria-hidden="true" class="aal_anchor" id="calling-the-server-with-rest-api-through-central-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>Calling the server with REST API through central services</h2>



<p>Currently in Angular apps, in order to fetch data from the server, we usually import a service that handle the fetching logic for us:</p>



<pre class="wp-block-preformatted">var app = angular.module('myApp', ['ngResource']);app.factory("Friend", function($resource) {<br>  return $resource("/api/friend/:id");<br>});app.controller("FriendListItemCtrl", function($scope, Friend) {<br>  Friend.get({ id: 1 }, function(data) {<br>    $scope.friend = data;<br>  });<br>});</pre>



<p>When we moved to Component based architecture, we switched the Controller to the Component class, but in most examples out there, the way we fetch data hasn’t really changed.</p>



<pre class="wp-block-preformatted">...<br>import { Headers, Http } from '@angular/http';<br>import 'rxjs/add/operator/toPromise';import { Friend } from ‘./friend’;@Injectable()<br>export class FriendService {<br>  constructor(private http: Http) { }  getFriend(id: string): Promise&lt;Friend[]&gt; {<br>    return this.http.get(`/api/friend/${id}`)<br>                    .toPromise()<br>                    .then(res =&gt; res.json().data as Friend[]);<br>  }<br>}........................import { Component } from ‘@angular/core’;<br>import { FriendService } from ‘./friend.service’;...@Component({<br>  selector: ‘friend’,<br>  templateUrl: ......<br>})<br>export class FriendComponent implements OnInit {<br>  friend: Friend;  constructor(private friendService: FriendService){<br>    this.friendService.getFriend(id)<br>                      .then(friend =&gt; this.friend = friend);<br>  }<br>}</pre>



<p>And that introduces an issue — What happens if now we need to get different data from the server?</p>



<p><strong>Let’s look at an example of the issue,&nbsp;</strong>we’ll use this Component tree as an example:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="768" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_FBqKwp2v4wvhFEGYtUGDgg.jpg" alt="" class="wp-image-323" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_FBqKwp2v4wvhFEGYtUGDgg.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FBqKwp2v4wvhFEGYtUGDgg-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_FBqKwp2v4wvhFEGYtUGDgg-768x576.jpg 768w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>and let’s say the we call a service on the parent `FriendsList` Component that fetches all the data for the Component tree.</p>



<p>Now let’s ask two simple questions:</p>



<ol class="wp-block-list"><li><strong>What happens when we need to change &lt;FriendInfo&gt; Component to display new fields?</strong></li><li><strong>How do we reuse &lt;FriendInfo&gt; Component in a different place in our app and still fetch the data it needs?</strong></li></ol>



<p><strong>For the first question</strong>, we will need to change the server endpoint to either:</p>



<ul class="wp-block-list"><li>Change the existing one to fetch the new data (might change other Components who use the same endpoint and service)</li></ul>



<p>or</p>



<ul class="wp-block-list"><li>Add a new endpoint with the new data structure we want and change the service to support the new endpoint</li></ul>



<p>In either of those solutions — Our Components are no longer&nbsp;<strong>self contained</strong></p>



<p><strong>As for the second question</strong>, we would need to create or change the service to support the new Component tree that &lt;FriendInfo&gt; in under, making it&nbsp;<strong>not reusable!</strong></p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="990" height="308" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_zOY5GybNa8FxdBiLQCa9pw.png" alt="" class="wp-image-324" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_zOY5GybNa8FxdBiLQCa9pw.png 990w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zOY5GybNa8FxdBiLQCa9pw-300x93.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_zOY5GybNa8FxdBiLQCa9pw-768x239.png 768w" sizes="(max-width: 990px) 100vw, 990px" /><figcaption>A diagram I stole from a talk (referenced at the end) that shows that if child component’s AJAX requirements has changed, it will change the whole tree and the server as well</figcaption></figure>



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



<p>So what do we need that is missing with current solutions:</p>



<ol class="wp-block-list"><li>Each Component could&nbsp;<strong>specify its own data dependencies</strong>&nbsp;without knowing a central service or another parent Component in the current render tree</li><li>When we render a tree of Components, we will&nbsp;<strong>fetch exactly</strong>&nbsp;the information that this Component tree needs which is a&nbsp;<strong>combination of the requirements of each Component</strong></li><li>We would do that in&nbsp;<strong>one single request</strong></li><li>We need an&nbsp;<strong>API layer</strong>&nbsp;that will bring us&nbsp;<strong>new fields without changing</strong>&nbsp;existing and exposing new endpoint</li></ol>



<h2 class="wp-block-heading" id="5912"><a href="#solution-graphql-client" aria-hidden="true" class="aal_anchor" id="solution-graphql-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>Solution — GraphQL Client</h2>



<p>With GraphQL, we can&nbsp;<strong>co-locate the server data requirements</strong>&nbsp;for each Component, and then use a GraphQL Client like&nbsp;<a href="https://github.com/apollostack/angular2-apollo" target="_blank" rel="noreferrer noopener">angular2-apollo</a>&nbsp;to handle the merging of those needs into one single request that gets exactly what we need.</p>



<p>Let’s have a look:</p>



<p><strong>&lt;FriendsList&gt;</strong></p>



<pre class="wp-block-preformatted">import { Component } from '@angular/core';<br>import { Angular2Apollo } from 'angular2-apollo';<br>import gql from 'graphql-tag';<br><br>const FriendsQuery = gql`<br>  query getFriends {<strong><br>    friends {<br>      id<br>    }<br></strong>  }<br>`;<br><br>@Component({<br>  selector: 'friends-list',<br>  template: `<br>    &lt;div *ngFor="let friend of friends"&gt;<br>      &lt;friends-list-item [friendId]="friend.<strong>id</strong>"&gt;&lt;/friends-list-item&gt;<br>    &lt;/div&gt;<br>  `<br>})<br>export class FriendsListComponent {<br>  friends: FriendId[];<br><br>  constructor(private apollo: Angular2Apollo) {<br>    this.friends = this.apollo.watchQuery({<br>      query: <strong>FriendsQuery</strong><br>    });<br>  }<br>}</pre>



<p><strong>&lt;FriendsListItem&gt;</strong></p>



<pre class="wp-block-preformatted">import { Component, Input } from '@angular/core';<br>import { Angular2Apollo } from 'angular2-apollo';<br>import gql from 'graphql-tag';<br><br>const FriendItemQuery = gql`<br>  query getFriendItem($id: Int!) {<br><strong>    Friend(id: $id) {<br>      id<br>      is_viewer_friend<br>      profilePicture {<br>        url      <br>      }<br>    }</strong><br>  }<br>`;<br><br>@Component({<br>  selector: 'friends-list-item',<br>  template: `<br>    &lt;div&gt;<br>      &lt;img src="friend.<strong>profilePicture.url</strong>"/&gt;<br>      &lt;friend-info [friendId]="friend.<strong>id</strong>"&gt;&lt;/friend-info&gt;<br>      {{friend.<strong>is_viewer_friend</strong>}}       <br>    &lt;/div&gt;<br>  `<br>})<br>export class FriendListItemComponent {<br>  @Input() friendId: number;<br>  friend: FriendListItem;constructor(private  apollo: Angular2Apollo) {<br>    this.friend = this.apollo.watchQuery({<br>      query: <strong>FriendItemQuery</strong>,<br>      variables: {id: this.friendId}<br>    });<br>  }  <br>}</pre>



<p><strong>&lt;FriendInfo&gt;</strong></p>



<pre class="wp-block-preformatted">import { Component, Input } from '@angular/core';<br>import { Angular2Apollo } from 'angular2-apollo';<br>import gql from 'graphql-tag';<br><br>const FriendInfoQuery = gql`<br>  query getFriendInfo($id: Int!) {<br><strong>    Friend(id: $id) {<br>      id<br>      name<br>      mutual_friends {<br>        count      <br>      }<br>    }</strong><br>  }<br>`;<br><br>@Component({<br>  selector: 'friends-info',<br>  template: `<br>    &lt;div&gt;<br>      &lt;p&gt;{{friend.<strong>name</strong>}}&lt;/p&gt;<br>      &lt;p&gt;{{friend.<strong>mutual_friends.count</strong>}} mutual friends&lt;/p&gt;<br>    &lt;/div&gt;<br>  `<br>})<br>export class FriendInfoComponent {<br>  @Input() friendId: number;<br>  friend: FriendInfo;<br><br>  constructor(private  apollo: Angular2Apollo) {<br>    this.friend = this.apollo.watchQuery({<br>      query: <strong>FriendInfoQuery</strong>,<br>      variables: {id: this.friendId}<br>    });<br>  }  <br>}</pre>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>this is of course not a full working app, I’ll add links to full implementation at the end</p></blockquote>



<p>Now let’s get back to our original questions:</p>



<ol class="wp-block-list"><li><strong>What happens when we need to change &lt;FriendInfo&gt; Component to display new fields?</strong></li><li><strong>How do we reuse &lt;FriendInfo&gt; Component in a different place in our app and still fetch the data it needs?</strong></li></ol>



<p>The answer now, is that you only need to change &lt;FriendInfo&gt; Component itself and that’s it:</p>



<pre class="wp-block-preformatted">const FriendInfoQuery = gql`<br>  query getFriendInfo($id: Int!) {<br>    Friend(id: $id) {<br>      id<br>      name<br>      mutual_friends {<br>        count      <br>      }<strong><br>      age<br></strong>    }<br>  }<br>`;<br>...<br>  template: `<br>    &lt;div&gt;<br>      &lt;p&gt;{{friend.name}}&lt;/p&gt;<br>      &lt;p&gt;{{friend.mutual_friends.count}} mutual friends&lt;/p&gt;<br>      &lt;p&gt;{{friend.<strong>age</strong>}} years old&lt;/p&gt;<br>    &lt;/div&gt;<br>  `<br>})<br>export class FriendInfoComponent {<br>...  <br>}</pre>



<p>That’s it!</p>



<ul class="wp-block-list"><li>We don’t need to change any of its parent Components</li><li>We don’t need to change the API endpoint</li><li>We can move it around and reuse it in any Component tree</li></ul>



<p>It is now a true&nbsp;<strong>reusable, self contained</strong>&nbsp;Component.</p>



<h2 class="wp-block-heading" id="9084"><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>In this article I’ve tried to make the point that we should adjust our way of fetching data from the server to the new paradigms Angular 2.0 introduced.</p>



<p>It’s Important to note that those concepts and solutions are also true and valid in an&nbsp;<strong>Angular 1.x</strong>&nbsp;app that is Component based (and Apollo Client work with it as well).</p>



<p>Also, an important point is that you can use this solution alongside your regular REST services and not instead of them, add it where it fits and make sense to you.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>There are many more benefits for this type of architecture and more details about how we manage those queries and app state which I’ll touch on&nbsp;<a href="https://medium.com/apollo-stack/" target="_blank" rel="noreferrer noopener">later posts</a></p></blockquote>



<p>Here are few notable talks and resources about those techniques, some are for React but the concepts are still the same:</p>



<ul class="wp-block-list"><li><a href="https://www.youtube.com/watch?v=9sc8Pyc51uU" target="_blank" rel="noreferrer noopener">Data fetching for React applications at Facebook</a></li><li><a href="https://www.youtube.com/watch?v=qpGnPbpkcZM&amp;index=3&amp;list=PLhCf3AUOg4PgQoY_A6xWDQ70yaNtPYtZd" target="_blank" rel="noreferrer noopener">Modernize your Angular apps with GraphQL</a></li><li><a href="https://github.com/apollostack/GitHunt-angular2" target="_blank" rel="noreferrer noopener">Angular2-Githunt example</a></li></ul>



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



<p><em>To learn more about how Angular works with GraphQL, hear directly from Angular core team member Jeff Cross at the upcoming&nbsp;</em><a href="http://graphqlsummit.com/" target="_blank" rel="noreferrer noopener"><em>GraphQL Summit</em></a><em>&nbsp;in San Francisco on October 26th!</em></p>


Data management and AJAX server fetching for Angular Component based apps


<p>Apollo Client is a simple yet functional GraphQL client that works with any front-end and any GraphQL spec-compliant server.</p>



<p>Part of the reason developers choose to work with GraphQL, a fairly new technology, is the ease of querying nested application data while specifying only the fields that you need.</p>



<p>But hardly any application on the modern web is read-only. Handling users’ interactions often requires modifications to server-side data, keeping the browser’s state in sync, while looking fast and responsive to any actions.</p>



<p>As of a recent release, Apollo Client now provides simple tools to work with mutations while keeping store updates and rerenders efficient.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Interested in learning more about Apollo and our future goals? Ask questions during our&nbsp;<a href="https://hashnode.com/ama/with-apollo-team-ciqanu1mh002l8b53of65z3da" target="_blank" rel="noreferrer noopener">AMA on Hashnode</a>&nbsp;on July 26, 2016 — it starts at 11 AM Pacific time!</p></blockquote>



<h2 class="wp-block-heading" id="df44"><a href="#firing-a-mutation" aria-hidden="true" class="aal_anchor" id="firing-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>Firing a Mutation</h2>



<p>A typical GraphQL mutation has two major parts: what mutation to call with what parameters, and what the mutation should return on its success.</p>



<p>Here is what a mutation call looks like in Apollo Client using the GraphQL mutation syntax:</p>



<pre class="wp-block-preformatted">client.mutate({<br>  mutation: gql`<br>    mutation ($text: String!, $list_id: ID!) {<br>      addNewTask(text: $text, list_id: $list_id) {<br>        id<br>        text<br>        completed<br>        createdAt<br>      }<br>    }<br>  `,<br>  variables: {<br>    text: 'walk the dog',<br>    list_id: '123',<br>  },<br>})</pre>



<p>It is a standard GraphQL mutation query string, with arguments passed via variables — just like what you would type in GraphiQL.</p>



<h2 class="wp-block-heading" id="413d"><a href="#updating-query-results" aria-hidden="true" class="aal_anchor" id="updating-query-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>Updating Query Results</h2>



<p>After a mutation has fired and the data has changed on the server, users expect all parts of the UI to reflect the changes that they have made. If we don’t need to be efficient, the easiest way to do this is simply to refetch all of the queries we are currently looking at. But if we want to transfer the minimal information over the wire to keep the client in sync, we need to manually handle the mutation return value and update our results in a fine-grained way.</p>



<p>Apollo Client now gives you a way to update any queries currently being watched with the result of a mutation. This way, you can append a newly created object to the correct location, or update some specific fields without having to refetch anything.</p>



<p>Let’s look at an example. Let’s say there is a query that fetches the list of tasks for the currently selected list:</p>



<pre class="wp-block-preformatted">query todos($list_id: ID!) {<br>  todo_list(id: $list_id) {<br>    title<br>    tasks {<br>      id<br>      text<br>      completed<br>      createdAt<br>    }<br>  }<br>}</pre>



<p>… then when you call a mutation creating a new task, you can easily update the query above using the new&nbsp;<em>updateQueries</em>&nbsp;option to&nbsp;<em>client.mutate</em>:</p>



<pre class="wp-block-preformatted">client.mutate({<br>  mutation: ...,  // same as above<br>  variables: ..., // same as above<br>  updateQueries: {<br>    todos: (previousQueryResult, { mutationResult }) =&gt; {<br>      return {<br>        title: previousQueryResult.title,<br>        tasks: [...previousQueryResult.tasks, mutationResult],<br>      };<br>    },<br>  },<br>});</pre>



<p>You can see above that updating a query result is as simple as writing a reducer function, a concept borrowed from&nbsp;<a href="http://redux.js.org/docs/basics/Reducers.html" target="_blank" rel="noreferrer noopener">Redux reducers</a>: it is a function that takes the old query result, a new object (in this case, the mutation result) and combines them together into the new query result.</p>



<h2 class="wp-block-heading" id="93e6"><a href="#optimistic-ui" aria-hidden="true" class="aal_anchor" id="optimistic-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>Optimistic UI</h2>



<p>The story about mutations would have ended here if the Internet operated with zero latency from any part of the world. Unfortunately, that’s not the case, which means that every communication with the server takes a significant delay.</p>



<p>Users have grown to expect an instant response to most trivial interactions with a website or an app. They expect the UI to react immediately and the changes to persist in the background.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="768" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_RouBLrh2fM1wYjx6Af8Gfg.png" alt="" class="wp-image-284" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_RouBLrh2fM1wYjx6Af8Gfg.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RouBLrh2fM1wYjx6Af8Gfg-300x225.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_RouBLrh2fM1wYjx6Af8Gfg-768x576.png 768w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>Turns out, this is something an application can deliver most of the time. Whenever we create a new task in a todo list, or remove an image from a grid — we can simulate the result by guessing what will happen, and then validate the behavior with the server. The trick is to update the UI state with a fake response first, and then re-validate it once the server responses. This is what we call&nbsp;<a href="http://info.meteor.com/blog/optimistic-ui-with-meteor-latency-compensation" target="_blank" rel="noreferrer noopener">Optimistic UI</a>.</p>



<p>Apollo Client gives a very simple way to specify what is the “guesstimate” response from the server. The optimistic update is always rolled back once we find out the real result from the server, so the user sees the “fake” only until the request to the server returns or times out.</p>



<p>To specify the predicted server result, just use the new&nbsp;<em>optimisticResponse</em>&nbsp;option to&nbsp;<em>client.mutate</em>:</p>



<pre class="wp-block-preformatted">client.mutate({<br>  mutation: ...,            // same as above<br>  variables: ...,           // same as above<br>  updateQueries: ...,       // same as above<br>  optimisticResponse: {<br>    id: generatedId,<br>    text: text,             // this is one of the arguments<br>    createdAt: +(new Date), // not accurate, but close<br>    completed: false,       // assume task is created not completed<br>  },<br>});</pre>



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



<p>As you might have noticed, your reducer function always operates on the query result, and not some normalized format. But don’t be fooled! Internally, Apollo Client normalizes the results of both queries and mutation updates into a store, to get benefits such as query caching and consistency across the store. You can open up Redux dev-tools and inspect how Apollo Client’s integrates these results into the internal state format.</p>



<h2 class="wp-block-heading" id="c0a6"><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>Apollo Client now gives application developers convenient tools to work with GraphQL mutations, taking care of maintaining the intermediate state, applying an optimistic result, and finally replacing it with a server response.</p>



<p>Importantly, Apollo Client provides a familiar interface (reducer functions) to a mechanism to keep the queries used on the screen in sync after every mutation, so you don’t have to learn about cache internals to update your screen.</p>


Mutations and Optimistic UI in Apollo Client

How Facebook organizes their GraphQL code


<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="(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-to

Enhanced Checks and Observability in GraphOS

How to use Apollo Client with Next.js 13

How to use Apollo Client with Remix

Building a GraphQL server in Go with go-graphql

How to use Apollo Sandbox on your localhost

How to embed Explorer for a private graph

Using the GitHub GraphQL API with Apollo Studio Explorer

Past posts

Using GraphQL with Python – A Complete Guide

Testing Apollo Client Applications

TypeScript GraphQL Code Generator – Generate GraphQL Types with Apollo Codegen Tutorial

Learn GraphQL – Tutorials for Fullstack GraphQL

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

How to use GraphQL with Postman – Postman testing with GraphQL

How-to

Enhanced Checks and Observability in GraphOS

How to use Apollo Client with Next.js 13

How to use Apollo Client with Remix

Building a GraphQL server in Go with go-graphql

How to use Apollo Sandbox on your localhost

How to embed Explorer for a private graph

Using the GitHub GraphQL API with Apollo Studio Explorer

Past posts

Using GraphQL with Python – A Complete Guide

Testing Apollo Client Applications

TypeScript GraphQL Code Generator – Generate GraphQL Types with Apollo Codegen Tutorial

Learn GraphQL – Tutorials for Fullstack GraphQL

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

How to use GraphQL with Postman – Postman testing with GraphQL

Stay in our orbit