Enhance customer experiences with Apollo GraphOS


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



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



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



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



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



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



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



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

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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


More expressive schemas with @oneOf


<p><em>Caching, Native Cost Calculation and Limiting, and Telemetry Capabilities Revolutionize API Management and Streamline Building Cross-Platform Digital Application Experiences</em></p>



<p>Today at PlatformCon, <a href="https://apollographql.com">Apollo GraphQL</a>, the creator of GraphQL federation, announced new features in <a href="https://www.apollographql.com/graphos/">Apollo GraphOS</a> are now generally available to better leverage GraphQL’s developer productivity and performance benefits at any scale. This release provides API platform teams with visibility, usability, and performance benefits for GraphQL federation, enabling the engineering teams they serve to maximize the value of their APIs across their business.</p>



<p>As the leading GraphQL federation platform, GraphOS provides an abstraction layer for API complexity, enabling product engineering teams to rapidly build and iterate features based on customer demand. <a href="https://www.apollographql.com/resources/gartner-when-to-use-graphql-to-accelerate-api-delivery">Gartner® predicts that </a>30% of enterprises using GraphQL will utilize GraphQL federation by 2027, up from less than 5% in 2024.<sup>1 </sup>Apollo believes this trend suggests the number of enterprises using GraphQL federation as their API access layer will increase by 12x. GraphOS provides everything enterprise teams need to deliver GraphQL federation at any scale.&nbsp;</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p>“GraphQL federation removes the friction between the frontend and backend that we see in distributed architectures,” said Matt DeBergalis, Chief Technology Officer and co-founder at Apollo GraphQL. “This latest GraphOS release enables API platform teams to operationalize GraphQL federation’s benefits faster, so they can focus less on building custom tooling and more on their customers’ needs.”</p>
</blockquote>



<p>This latest GraphOS release includes significant improvements around observability, usability, and performance, enabling API platform teams to operate GraphQL federation more easily than ever before.&nbsp; “At enterprise-scale, every millisecond of latency in your consumer’s digital experiences impacts the bottom line,” said Rob Brazier, VP of Product at Apollo GraphQL. “With this release of Apollo GraphOS, we’ve made it even easier for API platform teams to observe and optimize the performance of federated graphs.”&nbsp;</p>



<p><strong>Apollo’s latest release provides operational excellence for GraphQL federation</strong></p>



<p>GraphQL federation is becoming a de facto architecture for platform engineering teams to simplify API governance across distributed architectures. Client teams can fetch all the data they need from a single endpoint, and this paradigm enables API platform teams to enforce better governance, provide better visibility into service usage, as well as use standardized tools for performance. GraphOS provides a complete solution for delivering GraphQL federation at any scale:</p>



<div class="wp-block-group is-vertical is-layout-flex wp-container-core-group-is-layout-2 wp-block-group-is-layout-flex">
<ul class="wp-block-list">
<li><strong>Better application performance</strong> – Apollo introduces an improved and simplified form of API caching built for GraphQL federation. GraphOS’s caching layer spans any number of APIs and now, in public preview, supports entity caching. Entities are object types that are composed from multiple GraphQL APIs and are the business objects or “nouns of every business.” API platform teams can store entities such as their inventory, products, or user records in a Redis data store. API platform teams can set how long these entities are cached in the data store, enabling API platform teams to significantly improve performance across an entire fleet of applications. &#8220;We&#8217;ve rolled out entity caching in production and are observing a decrease in median response time,&#8221; said Nimit Barochia, Senior Principal Software Engineer at Dow Jones. &#8220;The major improvement is how much less traffic we send to our subgraphs. Like a 8-10x decrease in some cases.&#8221;</li>
</ul>



<ul class="wp-block-list">
<li><strong>Cost control </strong>– API platform teams need a means to ensure that costly GraphQL operations don’t slow performance or create a denial of service. Platform teams need a means to limit cost of GraphQL operations processed by the GraphOS Router. Apollo is adding in public preview native cost calculation and limiting to GraphOS to make it easy for platform teams to centrally implement this, rather than relying on underlying services.</li>



<li><strong>Stronger support and improved performance</strong> – Micro-frontends provide a frontend architecture that refines performance and composability across mobile and web applications. To improve performance, micro-frontend UIs typically batch multiple client operations, issued close together, into a single API request. GraphOS is adding better support for these use cases, enabling GraphOS to handle batched requests from clients to a supergraph. It also further augments performance by ensuring that batches are kept intact when processed and passed on to the required subgraphs.</li>



<li><strong>Enhanced telemetry</strong> – API platform teams need both standardized and custom metrics to better optimize federated graphs for performance and business objectives. GraphOS now provides unparalleled visibility to debug and optimize federated graphs, enabling these teams to import these metrics into their Application Performance Monitoring tool of choice for better decision-making.&nbsp;</li>



<li><strong>Significant improvements to the GraphOS management plane</strong> – In Apollo Studio, schema checks and insights enable API teams to build, test, and ship changes to their federated graph with confidence. This release features significant UX improvements and better insights, enabling API teams to ship changes faster without introducing breaking changes to downstream clients.</li>
</ul>
</div>



<p><strong>Apollo customers to focus on innovation instead of API aggregation or orchestration</strong></p>



<p>AI is driving rapid innovation across industries, making the API layer critical for delivering competitive, personalized applications. Apollo aims to help API platform teams leverage GraphQL federation’s benefits across engineering organizations, empowering their teams to lead their organizations into the AI era.&nbsp;</p>



<p><strong>Learn more with Apollo&nbsp;</strong></p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/events/apollo-graphos-summer-update-operational-excellence-for-graphql-federation?utm_campaign=2024-06-12_Webinar_Apollo-GraphOS-Summer-Update-Operational-Excellence&amp;utm_medium=email&amp;utm_source=sales">Attend a webinar</a> on June 12 to learn more about what’s new in GraphOS and see new features demoed.&nbsp;</li>



<li>Join Apollo <a href="https://lu.ma/platformcon-watch-party-apollo">live on June 13 </a>in NYC as it celebrates the largest conference for platform engineering, PlatformCon, and hear from customers COX Automotive, The New York Times, and Wayfair on how they’re finding success with Apollo’s federated GraphQL technology.</li>



<li>And the largest gathering of GraphQL enthusiasts and API platform teams is coming. Join Apollo at <a href="https://summit.graphql.com/">GraphQL Summit</a>, October 8-10, where engineering teams can learn from industry leaders spearheading successful GraphQL deployments at scale.</li>
</ul>



<p><sup>1</sup>Gartner, When to Use GraphQL to Accelerate API Delivery, By Shameen Pillai, et al, March 7, 2024. GARTNER is a registered trademark and service mark of Gartner, Inc. and/or its affiliates in the U.S. and internationally and is used herein with permission. All rights reserved.</p>



<h1 class="wp-block-heading"><a href="#about-apollo-graphql" aria-hidden="true" class="aal_anchor" id="about-apollo-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>About Apollo GraphQL</h1>



<p><a href="https://apollographql.com">Apollo GraphQL </a>helps developers help the world by providing a better API platform across teams. Apollo’s open-source software is downloaded 25M times per month and its commercial GraphQL technologies power the most innovative brands today. Teams at Netflix, Snap, and the New York Times ship personalized, omnichannel experiences faster with a supergraph – a self-service GraphQL platform that spans any number of backend services. Serving over 5T requests in 2023, the Apollo GraphOS<sup>TM</sup> platform simplifies API development with workflows and infrastructure to build, test, and ship supergraphs at any scale. Based in San Francisco, Apollo is backed by Insight Partners, Andreessen Horowitz, Matrix Partners, and Trinity Ventures. Learn more at: <a href="https://www.apollographql.com">https://www.apollographql.com</a>.</p>


Apollo GraphQL Announces Major GraphOS Update, Enhancing Observability and Performance for Enterprise-Scale GraphQL Federation


<p>GraphQL provides a self-service developer experience by enabling client teams to fetch all of the data they need with a single query. When implementing GraphQL at scale, it’s important to balance its flexibility with security measures that prevent bad actors from exploiting its self-serve nature.</p>



<p>A supergraph provides a unified but modular approach to GraphQL at scale. Not only does this simplify data fetching for client teams – it has immense benefits around visibility, security, and scalability for the platform teams who support these APIs. By using GraphOS, platform teams can block malicious traffic at the edge of the graph, define both cross-cutting and fine-grained security policies across any number of services, and provide defense in depth.</p>



<p>If you’re running a supergraph with Apollo GraphOS Enterprise, here are three ways you can use GraphOS to better secure the services in your GraphQL API:</p>



<h2 class="wp-block-heading"><a href="#centralize-authorization-in-the-router" aria-hidden="true" class="aal_anchor" id="centralize-authorization-in-the-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>Centralize authorization in the router</h2>



<p>The Apollo Router provides client teams with a central access point for any number of GraphQL services.&nbsp; This isn’t just convenient for client teams – it also provides a policy enforcement point (PEP) for security teams. </p>



<p>Rather than relying on your services to block unauthorized access, GraphOS allows you to proactively and declaratively enforce authentication and authorization centrally in the router for your supergraph. Enforcing authorization in the router reduces the request load on your services by blocking unauthorized requests at the edge of the API stack and eliminates the need for any custom APIM code used to centralize enforcement.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="512" src="https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized-1024x512.png" alt="" class="wp-image-22690" srcset="https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized-1024x512.png 1024w, https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized-768x384.png 768w, https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized-1536x768.png 1536w, https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized-1200x600.png 1200w, https://wp.apollographql.com/wp-content/uploads/2023/10/GraphOS-Authorization-unauthorized.png 1600w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>To set up authz enforcement in your router:</p>



<ol class="wp-block-list">
<li>Ensure that your router is <a href="https://www.apollographql.com/docs/router/enterprise-features/#enabling-enterprise-features">authenticated with your GraphOS Enterprise credentials</a></li>



<li>Configure your router to add claims to requests’ contexts with the Apollo Router’s built-in support for <a href="https://www.apollographql.com/docs/router/configuration/authn-jwt">JWT authentication</a> or with an <a href="https://www.apollographql.com/docs/router/customizations/coprocessor#adding-authorization-claims-via-coprocessor">external coprocessor</a>.</li>



<li>Create a declarative access control model in your schema with the <code>@requiresScopes</code> and <code>@authenticated</code> directives</li>
</ol>



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



<p>One of the most common objections to GraphQL is that it allows unbounded operations — a trait that can degrade performance or result in denial-of-service if too many complex queries are sent to the endpoint. But in the case that your GraphQL endpoint only serves first-party apps, there is no need for it to allow unbounded operations. Instead, you should reduce the surface area of your graph by only allowing the exact operations required by your applications.&nbsp;</p>



<p>GraphOS allows you to do exactly that by registering and safelisting operations that you trust. Create a list of registered operations in GraphOS Studio, and turn on safelisting in your router to block any non-registered operations. To further improve performance, you can also generate unique IDs for each operation and send only the ID in the request to your router rather than the full query string.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="512" src="https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1-1024x512.png" alt="" class="wp-image-22696" srcset="https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1-1024x512.png 1024w, https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1-768x384.png 768w, https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1-1536x768.png 1536w, https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1-1200x600.png 1200w, https://wp.apollographql.com/wp-content/uploads/2023/10/PQs_new-1.png 1600w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>In addition to safelisting operations, it’s also prudent to enforce general complexity limits on operations to prevent any intentional or unintentional misuse of your graph. For example, allowing operations with thousands of root fields or aliases is neither efficient nor necessary.&nbsp;</p>



<p>With GraphOS, you can implement simple limits on operation depth, height, aliases, and root fields to prevent malformed operations from degrading performance.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="512" src="https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new-1024x512.png" alt="" class="wp-image-22698" srcset="https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new-1024x512.png 1024w, https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new-300x150.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new-768x384.png 768w, https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new-1536x768.png 1536w, https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new-1200x600.png 1200w, https://wp.apollographql.com/wp-content/uploads/2023/10/operation_limits_new.png 1600w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>Join API architects, engineers, and experts from Apollo at <a href="https://summit.graphql.com/event/c51538f6-4b76-44e3-871e-54180c77cad8/websitePage:aa37bf00-dba5-4e19-912a-01aad46f7426">GraphQL Summit</a> October 9-12, 2023 to discuss real-world GraphQL security challenges and best practices. If GraphQL security is your thing, these are a few sessions you won’t want to miss:</p>



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



<p>Doyensec, the premier GraphQL security consultancy, will be onsite at GraphQL Summit! Stop by on Wednesday, October 11 and Thursday, October 12 for a free consultation to discuss technical security recommendations and engineering best practices with the experts who led the Apollo Router security audits.</p>



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



<p>This talk will discuss, in depth, how to defend against hackers conducting Reconnaissance, Denial of Service, Information Disclosure, Authentication and Authorization Bypass, Injection, Request Forgery and Hijacking, XSS, SQLi and Code Execution.</p>



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



<p>GraphQL&#8217;s &#8220;ask for what you need and get exactly that&#8221; is great, but it can also be exploited to &#8220;get what they want without your permission and crash your app&#8221;. To protect your GraphQL server, it is important to understand the different ways in which it can be abused.</p>



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



<p>In an enterprise supergraph like T-Mobile&#8217;s, clients will require fine-grained permissions for different operations and fields. With the flexibility in Apollo Gateway and Router to add external co-processing of requests, attribute-based access control (ABAC) and other customizations can control client traffic at the supergraph entry point.</p>



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



<p>This lab will provide a hands-on tour of observability tools that can be configured in a supergraph. You&#8217;ll learn how to observe the behavior and performance of your supergraph using both GraphOS reporting and cloud-native telemetry.</p>



<p><strong>For a full list of talks on GraphQL security and more, check out the </strong><a href="https://summit.graphql.com/event/c51538f6-4b76-44e3-871e-54180c77cad8/websitePage:aa37bf00-dba5-4e19-912a-01aad46f7426"><strong>GraphQL Summit agenda</strong></a><strong>. We hope to see you there!</strong></p>


Enforcing GraphQL security best practices with GraphOS


<p>Nullability is a fundamental concept in many programming languages giving us the ability to express the absence of a value or assigned object. This is particularly relevant in strongly typed languages where each constant or variable must be defined with one of the language data types or explicitly allowed to be null.</p>



<p>GraphQL is strongly-typed and all fields are, by default, nullable with <code>null</code> being a valid response for any field unless explicitly declared otherwise. In GraphQL syntax a trailing exclamation mark is used to denote a field that uses a <a href="https://spec.graphql.org/draft/#sec-Non-Null">Non-Null</a> type, like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">{
  nullableField: String
  nonNullableField: String!
}</code></pre>



<p>Strong typing is also one of the defining characteristics of Swift where the use of the <a href="https://developer.apple.com/documentation/swift/optional"><code>Optional</code></a> type ensures that nullable (<code>nil</code>) values are handled explicitly. Swift default type behavior is the opposite of GraphQL, though, and types are defined as non-null unless explicitly declared otherwise. The question mark on a type declaration indicates that the value it contains is optional (nullable), like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">let nonOptionalValue: String
let optionalValue: String?</code></pre>



<p><em><strong>Note: </strong>GraphQL has <a href="https://spec.graphql.org/draft/#sec-Non-Null.Nullable-vs-Optional">concepts</a> of both Nullable and Optional, and there is semantic overlap with the Swift <code>&lt;a href=&quot;https://developer.apple.com/documentation/swift/optional&quot;&gt;Optional&lt;/a&gt;</code> type. It is worth taking the time to understand each to avoid confusion.</em></p>



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



<p>In the section above, we showed how nullability is an integral part of both languages. Let’s explore how nullability is used in the Swift code generated by Apollo iOS.</p>



<p>During code generation when a GraphQL field type is defined as nullable, Apollo iOS will translate that into a Swift <code>Optional</code> type, allowing the generated model to receive <code>null</code> as a valid response for that field.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">type Query {
  allAnimals: [Animal]
}

interface Animal {
  species: String # &lt;- nullable
}

type Predator implements Animal {
  species: String # &lt;- nullable
}

type Pet implements Animal {
  species: String # &lt;- nullable
  name: String # &lt;- nullable
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">query AllAnimals {
  allAnimals {
    species
  }
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">class AllAnimalsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    struct AllAnimal: SelectionSet {
      var species: String? { get } // &lt;- optional
    }
  }
}</code></pre>



<p><em><strong>Note: </strong>There are cases where non-nullable fields will be generated as nullable by using the <code>@include</code> or <code>@skip</code> directives. In these cases, the field can be returned as <code>null</code> and therefore a Swift <code>Optional</code> type is needed.</em></p>



<p>If you’ve used Apollo iOS to generate Swift code before you might have noticed that some fragment accessors are generated as optional too. This is because the fragment’s fields might not be returned in the response depending on the object’s type.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">query AllAnimals {
  allAnimals {
    species
    ... on Pet {
      ...PetDetails
    }
  }
}

fragment PetDetails on Pet {
  name
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">class AllAnimalsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    struct AllAnimal: SelectionSet {
      var species: String? { get } // &lt;- optional
      var asPet?: AsPet { _asInlineFragment() } // &lt;- optional
      
      struct AsPet: InlineFragment {
        var name: String? { get } // &lt;- optional
      }
    }
  }
}</code></pre>



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



<p>So far we’ve explored nullability in GraphQL and Swift, but we still haven’t encountered the <code>GraphQLNullable</code> type yet. Looking at the way nullable types are defined in both languages it is reasonable to assume that they can be expressed in the same way, albeit with slightly different syntax. However, that’s not true.</p>



<p>A Swift <code>Optional</code> either has a value, which must be unwrapped, or there is no value. Similarly, GraphQL types either have a value or there is no value but, most importantly, <a href="https://spec.graphql.org/draft/#sec-Null-Value">null</a> values have two semantically different ways to represent the lack of a value: <em>explicitly</em> by providing the literal value: <code>null</code>; <em>implicitly</em> by not providing a value at all. Trying to reconcile this difference is where <code>GraphQLNullable</code> is required.</p>



<p>n the same way that Swift’s <code>Optional</code> type is an enum, <code>GraphQLNullable</code> is also a Swift <code>enum</code> providing the <code>some</code> and <code>none</code> cases but additionally the third possible case allowed by GraphQL &#8211; <code>null</code>.</p>



<ul class="wp-block-list">
<li><code>some</code> represents the presence of a value</li>



<li><code>none</code> represents the <em>implicit</em> absence of a value, aka <code>nil</code></li>



<li><code>null</code> represents an <em>explicitly</em> null value</li>
</ul>



<p><code>GraphQLNullable</code> is not needed in the generated response models though because whether a GraphQL response contains <code>null</code> for a field or the field is not present, both are represented in the generated response as a Swift optional. The only time a field is allowed to be missing from a GraphQL response is as a result of the <code>@include</code>, <code>@skip</code> or <code>@defer</code> directives. Any other time a field is missing would indicate a partial response due to a <a href="https://spec.graphql.org/draft/#sec-Errors.Field-Errors">field error</a>.</p>



<p>It is only on input types where the subtle <a href="https://spec.graphql.org/draft/#sec-Null-Value">difference</a> between <code>nil</code> and <code>null</code> becomes important. In a mutation or input variable, an explicit <code>null</code> value could be taken to represent the deletion of a field, whereas the absence of an explicit value (i.e.: <code>nil</code>) could be taken to imply no change to the field. Unfortunately, some GraphQL server implementations simply treat them the same, and many developers who use GraphQL are unaware of the difference. This is also in contrast to type-safe languages which cannot discern the difference between explicit or implicit <code>nil</code>.</p>



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



<p>Apollo iOS is a general-purpose GraphQL client and must comply with the full <a href="https://spec.graphql.org/">GraphQL specification</a>. We needed to make it clear that there is a difference, and you should be explicit in what you want. Therefore, the design of <code>GraphQLNullable</code> forces the user to select a case that signals their intent without question.</p>



<p><code>GraphQLNullable</code> was introduced with the major <code>1.0</code> release and is, without doubt, an improvement over the previous syntax of double-optional. Developers were often confused by this syntax where an inner optional with a value of <code>nil</code> combined with an outer optional value of <code>some</code> would mean the GraphQL value <code>null</code>, while an outmost optional of <code>nil</code> would mean the absence of a value, aka. <code>nil</code>. We received plenty of questions about why values were doubly wrapped in optional and it would often lead to easy mistakes in using <code>nil</code> when you actually wanted <code>null</code> but the compiler could never know what your intent was.</p>



<p>The change to <code>GraphQLNullable</code> hasn’t been without friction, though, and most of the feedback we have received is from developers who say they do not need to be concerned with the difference between <code>nil</code> and <code>null</code>. We believe in the value of being explicit, but it does make the usage of these fields more cumbersome because of having to use the verbose syntax of <code>.some()</code> or <code>GraphQLNullable()</code>, especially when combined with another <code>enum</code> type such as <code>GraphQLEnum</code>.</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>



<p>Consider the following definitions:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">struct Filter {
  let species: String
  let name: String? = nil
  let predator: Bool
}

var filter: GraphQLNullable&lt;Filter&gt;

// Implicitly stating the absence of a value, aka nil.
filter = .none 

// Explicitly stating a null value
filter = .null

// Stating the presence of a value
filter = .some(.init(
  species: &quot;Canine&quot;, 
  predator: false
))</code></pre>



<p>As you can see above, the <code>none</code> and <code>null</code> cases are easy enough to use and clear in their semantics, whereas having to wrap values in <code>some</code> is awkward and less clear to someone reading the code who may be unfamiliar with <code>GraphQLNullable</code>.</p>



<p>For additional convenience, you&#8217;ll find that <code>GraphQLNullable</code> conforms to Swift’s <code>ExpressibleBy</code> protocols that match GraphQL&#8217;s scalar types, such as <code>ExpressibleByStringLiteral</code>, <code>ExpressibleByIntegerLiteral</code>, etc. So if your <code>GraphQLNullable</code> property is wrapping a GraphQL scalar type, then initialization can be done as follows:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">let aString: GraphQLNullable&lt;String&gt; = &quot;value&quot;
let aBool: GraphQLNullable&lt;Bool&gt; = true
let aInt: GraphQLNullable&lt;Int&gt; = 123
let aDouble: GraphQLNullable&lt;Double&gt; = 1.1</code></pre>



<p><code>GraphQLNullable</code> also has a convenient nil coalescing operator useful in cases where the value being evaluated is optional itself:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">let species: GraphQLNullable = optionalValue ?? .null</code></pre>



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



<p>Despite the conveniences, we’ve seen that the <code>some</code> case is still awkward to use. For those who aren’t concerned about the semantic difference of <code>nil</code> and <code>null</code> there have been suggestions from the community for an extension on <code>GraphQLNullable</code> that can help with the initialization of nullable values.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">extension GraphQLNullable {
  init(optionalValue value: Wrapped?) {
    if let value {
      self = .some(value)
    } else {
      self = .none // &lt;- change this to .null if your server requires
    }
  }
}</code></pre>



<p><em><strong>Note: </strong>We choose not to provide this extension by default in Apollo iOS because the decision to return <code>.none</code> vs. <code>.null</code> is going to be specific to how your connecting GraphQL server interprets nullable values. You should take the time to fully understand the impact of this extension and what the resultant input field value is signaling to your server.</em></p>



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



<p>GraphQL and Swift are a good fit. They are both strongly typed and have nullability built-in. Their syntax is quite similar even if the defaults are different and the details of handling <code>null</code> vs <code>nil</code> can get complicated for input values.</p>



<p>I hope this article cleared up some of the confusion around <code>GraphQLNullable</code> and provided you with some insight into its design.</p>



<p>We welcome your feedback, and please don’t hesitate to reach out on <a href="https://github.com/apollographql/apollo-ios">GitHub</a>, the <a href="https://community.apollographql.com/tag/mobile">Apollo Community</a>, or the <a href="https://discord.gg/graphos">Apollo Discord</a> server.</p>


GraphQLNullable is not a trap!

Add Python to your GraphQL API with GraphOS and Strawberry GraphQL


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

Getting Started with Vue Apollo


<p><em><em>This is a guest post by Rares Matei, senior engineer at Nrwl.io. He created a course on Apollo Client called <a href="https://app.egghead.io/playlists/manage-state-in-react-apps-with-apollo-client-and-graphql-a45b3b89">Manage State in React Apps with Apollo Client and GraphQL.</a></em></em> <em>The course is free to take up until December 17th, 2021. </em></p>



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



<p>Apollo Client has a unique position in our front-end apps: like a proxy sitting right at the edge, all the outgoing and incoming requests go through it, it knows what data each component needs and what the server responds with. All this knowledge puts it in a uniquely powerful position. And it turns out Apollo Client handles all this responsibility beautifully: with its powerful cache, baked-in defaults for keeping interactions fast, APIs for handling the most common frontend problems, and tools for plugging in your local state and even handling REST requests, you&#8217;ll notice it guides you towards better user experience and writing more maintainable and readable components.</p>



<h2 class="wp-block-heading"><a href="#synchronise-server-and-client-state" aria-hidden="true" class="aal_anchor" id="synchronise-server-and-client-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>Synchronise server and client state</h2>



<p>Synchronizing data between a client app and a server is hard. You make the request, wait for it to resolve, you then need to parse the response and update your local model, and finally, you have to ensure all your components are properly connected to your different data points so that they re-render when a change occurs. If your request actually mutates data on the server, then it gets even trickier since you need to make sure the mutation happens in local memory as well.</p>



<p>Apollo abstracts all that away with a powerful in-memory cache: your components declare what data they want in the shape that they want it and Apollo will start building up this local sub-graph representation of your server graph, and ensure no unnecessary network requests are ever made. If two components end up requesting the same slice of your sub-graph, regardless of how they define their queries, Apollo will point them to the same location in the cache.</p>



<p><a href="https://app.egghead.io/lessons/apollo-why-have-a-client-side-graphql-cache">Just by using Apollo Client to make your queries, without any special configuration, your app will become faster.</a> (I created a series of videos around this, and if you click some of the links in this article, I will go more in-depth around some of the topics)</p>



<p>Do you need to make a mutation? <a href="https://app.egghead.io/lessons/apollo-update-the-local-cache-automatically-when-making-mutations">Apollo will automatically update its normalised representation of your updated object, and will re-render all components listening to that part of your graph</a>, regardless of the shape of their query.</p>



<p>And you are not locked into its default behaviours. If you have special cases where you need to reach into the cache to manually modify, <a href="https://app.egghead.io/lessons/apollo-manually-modify-the-cache-to-remove-deleted-items">Apollo fully opens that up with powerful APIs.</a></p>



<p>As you let Apollo worry about state management, and data synchronization your components will start becoming simpler, more maintainable. They&#8217;ll start describing the shape of the data they need in a single place. And Apollo <a href="https://app.egghead.io/lessons/apollo-use-read-field-policies-to-query-local-client-state">even allows us to sprinkle local client-only state in those queries, so that we don&#8217;t have to maintain a separate mechanism for handling it</a>:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="933" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-1024x933.png" alt="" class="wp-image-11487" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-1024x933.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-300x273.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-768x700.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-1200x1093.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM.png 1304w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="870" height="572" src="https://wp.apollographql.com/wp-content/uploads/2021/12/local_state_example.gif" alt="" class="wp-image-11489"/></figure>



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



<p>Working on front-end apps is challenging. You are operating on this small island where the only way to communicate with the outside world is via network requests. And those network requests can be fast, or occasionally very slow. They might throw an error. The server might change its data and you might be left displaying stale views to the user. And how would you even build a potentially infinitely scrolling list, like on Twitter?</p>



<p>While the cache sits at the core of Apollo, because of its unique position as a proxy of all incoming and outgoing network requests, it does offer lots of APIs on top of it to help with some of the most common frontend problems in existence:</p>



<ul class="wp-block-list"><li>simple, boolean &#8220;<a href="https://app.egghead.io/lessons/apollo-handle-loading-states-for-your-graphql-queries">loading</a>&#8221; and &#8220;<a href="https://app.egghead.io/lessons/apollo-handle-graphql-query-error-states-using-apollo">error</a>&#8221; states for each query</li><li><a href="https://app.egghead.io/lessons/apollo-use-the-retrylink-in-apollo-to-retry-queries-after-an-error">retries for your failed queries, with optional exponential back-off and jittering</a></li><li><a href="https://app.egghead.io/lessons/apollo-keep-queries-in-sync-with-the-backend-by-polling-for-new-data">simple polling for keeping queries in sync with your backend</a></li><li>after you&#8217;ve made a query, <a href="https://app.egghead.io/lessons/apollo-append-graphql-subscription-updates-to-existing-queries">you can subscribe for further real-time updates</a></li><li><a href="https://app.egghead.io/lessons/apollo-use-fetchmore-and-merge-field-policies-to-dynamically-load-more-items-into-a-list">build infinitely scrolling lists or paginate data</a></li><li><a href="https://app.egghead.io/lessons/apollo-use-optimistic-updates-to-build-uis-that-react-immediately-to-user-actions">enable optimistic updates</a> so that your UI updates instantly when you make a mutation, even if the server still hasn&#8217;t confirmed it. If there&#8217;s an error later on, Apollo automatically rolls back the optimistic UI update.</li><li>and many more!</li></ul>



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



<p>With its sensible defaults, but open APIs, Apollo lets you extend its capabilities as and when you need them. You are not locked into a specific workflow, and we briefly saw examples of this above when talking about handling local state and manually modifying the cache under advanced scenarios.</p>



<p>And with its extensible linker API, Apollo&#8217;s capabilities become ready to handle even the most advanced requirements.</p>



<p>Are you still using REST but are planning to migrate to GraphQL? <a href="https://app.egghead.io/lessons/apollo-incrementally-migrate-from-rest-to-graphql-using-the-restlink">You can start writing your components as if you are making GraphQL queries, and Apollo will transform them to REST calls behind the scenes</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="670" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-1024x670.png" alt="" class="wp-image-11491" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-1024x670.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-300x196.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-768x503.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-1200x786.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM.png 1390w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Another great example of this is <a href="https://app.egghead.io/lessons/apollo-provide-quick-app-start-up-times-by-syncing-the-apollo-cache-with-local-storage">syncing your in-memory cache to your browser&#8217;s localstorage</a>, to provide almost instant app start-up times.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="473" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-1024x473.png" alt="" class="wp-image-11493" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-1024x473.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-300x138.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-768x355.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-1200x554.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM.png 1382w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<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>Apollo does a lot out of the box. The more you trust and understand its cache, the less you&#8217;ll fight with hard-to-understand bugs. The more you read its docs, the higher the chance you&#8217;ll find an API that can elegantly handle a feature you&#8217;re building. And the more you get familiar with it, the more linkers you&#8217;ll find yourself using, that unlock new advanced capabilities.</p>



<p>Since using Apollo in my frontend projects, I&#8217;ve started enjoying the process of coding a lot more as well, because I don&#8217;t have to worry about whether I&#8217;m updating all my local data correctly and whether the right components know about the update. I get nudged towards creating better user experiences and writing simpler, more declarative code. Looking at how Apollo handles all the complex challenges of synchronizing data between the client and the server has taught me to become a better web developer myself, and I&#8217;ll continue to apply these learnings in all future projects I&#8217;ll work on, regardless of the technologies it uses.</p>



<p>And if you&#8217;d like to fully understand what I mean, regardless of whether you&#8217;ve never used Apollo before or are an advanced user, <a href="https://app.egghead.io/playlists/manage-state-in-react-apps-with-apollo-client-and-graphql-a45b3b89">I created a video course here where we&#8217;ll cover in-depth most concepts discussed in this article (and many more!), all while building practical features in a real-world app.</a> </p>


Why Apollo Client is an important tool in your GraphQL stack


<p>GraphQL is a query language and a server-side runtime (typically served over HTTP). However, you may have also heard of graph databases. What does GraphQL have to do with graph databases? Not so much.</p>



<p>In this post, we&#8217;ll clear up any confusion you may have about GraphQL and graph databases by learning about what graph databases are, the main ideas behind them, when they&#8217;re most valuable, and how they differ from GraphQL.</p>



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



<p>Graph databases are databases explicitly designed for the analysis of relationships. That is, we use graph databases when we&#8217;re interested in the <em>analysis of</em> <em>relationships between data</em> &#8212; not necessarily when we&#8217;re building the data store for your typical backend application.</p>



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



<p>Let&#8217;s understand graph databases by comparing them to something we&#8217;re familiar with: relational databases. With relational databases, the big selling point — at least from your typical backend application use case — is the fact that you get <strong>data integrity</strong> and <strong>constraints</strong>. We have to pre-define a data model, build it, and only then are the bounds upon which data can be created, read, updated, and deleted from within it realized. A pre-defined model is often critical for business applications, specifically the ability to enforce how data enters the database transactionally.</p>



<p>Graph databases don&#8217;t require a pre-defined data model. The idea of constraints is much more relaxed. We use graph databases to infer conclusions about our data later. Graph databases are more useful for data scientists who need to perform queries on relationships that would be otherwise extremely expensive (and perhaps impossible) from a relational standpoint.</p>



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



<p>Data enters a graph database through the abstractions of <strong>nodes</strong>, <strong>edges</strong>, and <strong>properties</strong> — all of which can be extended later on in the future without affecting existing functionality.</p>



<ul class="wp-block-list"><li>Nodes represent entities (like <code>Teacher</code> or <code>Student</code>).</li><li>Edges represent relationships between nodes (like the relationship between a <code>Teacher</code> and a <code>Student</code>). Edges also have directionality to them. For example, you could say that a <code>Teacher</code> is a <code>Teacher_of</code> a <code>Student</code>.</li><li>Properties exist to describe edges with more detail or to describe potential behaviors. For example, a <code>Student</code> and <code>Teacher</code> edge could contain properties that describe the <code>class_name</code> or <code>semester</code> in which the class was taken.</li></ul>



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



<p>What are some common use cases for graph databases? Some of the most popular use cases are:</p>



<ul class="wp-block-list"><li><strong>Fraud detection</strong></li><li><strong>Recommendation engines</strong></li><li><strong>IT network management</strong></li><li><strong>Graph algorithm computation</strong></li></ul>



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



<p>Fundamentally, there is no relationship. Besides the fact that GraphQL and graph databases have the word &#8220;graph&#8221; in their name, they were designed for two entirely separate purposes.</p>



<p>GraphQL, the query language, was created to make it easier for app developers fetch data by asking specifically for what they want, while graph databases were designed to allow for performant analysis of relationships between entities.</p>



<h3 class="wp-block-heading"><a href="#are-there-any-advantages-to-using-a-graph-database-as-your-data-source-for-your-graphql-api" aria-hidden="true" class="aal_anchor" id="are-there-any-advantages-to-using-a-graph-database-as-your-data-source-for-your-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>Are there any advantages to using a graph database as your data source for your GraphQL API?</h3>



<p>The main advantage I can think of for using a graph database as a data source is a shared mental model between edges, nodes, and properties between GraphQL and graph databases. You can model your GraphQL schema similarly to the way we think about the main abstractions in graph databases.</p>



<p>However, it&#8217;s a good idea to consider what you&#8217;re building. For many developers building standard web applications that rely on transactions and a constrained data model, a relational database may be a better choice.</p>



<p>Regardless, GraphQL is <em>data source agnostic</em>; that means that you could use anything you like as a data source, including a graph database. For example, you could use the <a rel="noreferrer noopener" target="_blank" href="https://neo4j.com/product/graphql-library/">Neo4j JavaScript Graph library</a> to serve data from your graph database over GraphQL.</p>



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



<p>In conclusion, GraphQL and graph databases are both graph-related by design, but we use them for entirely separate purposes. GraphQL is the query language used to design and query your company&#8217;s data graph in a typical web application architecture. In contrast, graph databases are a specialized type of database to analyze your data and draw useful conclusions.</p>


What is a Graph Database? | Why GraphQL is Not a Graph Database


<p>Trying to get buy-in to adopt GraphQL can be challenging when voices in the room provide inaccurate information about the technology. FUD (fear, uncertainty, and doubt) about things like security and caching can grind decision-making to a halt. These topics can be challenging to address without having access to and gathering the proper resources.</p>



<p>That&#8217;s why we&#8217;ve compiled a list of the five most common GraphQL misconceptions you might encounter, along with resources to help address any related concerns! In this article, we&#8217;ll learn about securing, caching, and scaling GraphQL APIs, what teams benefit the most from adopting it, and a bit of how GraphQL fits into the stack.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>If you&#8217;re looking for a comparison of REST vs. GraphQL, check out <a rel="noreferrer noopener" href="https://www.apollographql.com/blog/graphql/basics/graphql-vs-rest/" target="_blank">this article</a>. Unfamiliar with a lot of GraphQL vocabulary? Be sure to check out the<a rel="noreferrer noopener" href="https://www.apollographql.com/docs/resources/graphql-glossary/" target="_blank"> GraphQL Glossary</a>.</p></blockquote>



<h2 class="wp-block-heading"><a href="#1-graphql-isnt-secure" aria-hidden="true" class="aal_anchor" id="1-graphql-isnt-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. GraphQL isn&#8217;t secure.</h2>



<p>It&#8217;s true. A GraphQL API isn&#8217;t secure in the same way that a REST API isn&#8217;t secure until you take the necessary steps to ensure it.</p>



<p>When securing a GraphQL API, there are three main areas you&#8217;ll need to consider, <strong>authentication/authorization</strong>, <strong>reducing attack surface</strong>, and <strong>operations and governance</strong>.</p>



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



<p>GraphQL APIs still use <code>HTTP</code> as the transport protocol and, as such, can use the same authentication and authorization patterns used for REST APIs. The implementation details change, but GraphQL API developers can rely on the exact authentication strategies you use in REST APIs, like JWTs, and authorization strategies you would use in REST APIs, such as role or action-based authorization.</p>



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



<p>One of the benefits of using GraphQL is the powerful query language for data access and manipulation. However, this DSL opens up new attack vectors — such as query depth, query complexity, and batch query attacks — that malicious actors can use to target your APIs data or performance. However, these attacks and other common attack vectors faced by all APIs — such as rate-limiting — can all be prevented with existing solutions.</p>



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



<p>Beyond protecting your GraphQL API from bad actors and locking down private data, you also need a window into how your API is being used and by whom. GraphQL&#8217;s declarative query language combined with tracing makes it possible to identify anomalies — performance drops, error spikes, and traffic spikes — and trace them back to the actual operation and client.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Check out our <a rel="noreferrer noopener" href="https://www.apollographql.com/blog/graphql/security/9-ways-to-secure-your-graphql-api-security-checklist/" target="_blank">GraphQL Security Checklist</a> for an in-depth guide on securing your graph.</p></blockquote>



<h2 class="wp-block-heading"><a href="#2-you-cant-cache-graphql" aria-hidden="true" class="aal_anchor" id="2-you-cant-cache-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>2. You can&#8217;t cache GraphQL.</h2>



<p>Generally, when you hear this statement, what folks are referring to is <strong>edge caching</strong>. But, more specifically, they are discussing the difficulty of implementing a drop-in edge caching solution like a CDN.</p>



<p>By default, GraphQL uses the <code>POST</code> method for all requests. Most CDNs ignore <code>POST/PUT/DELETE</code> requests because they&#8217;re used for mutating data in REST APIs. However, we can still get edge caching in GraphQL by using <strong>cache hints</strong> and <strong>automatic persisted queries</strong>.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>We should always use a strategic approach to decide what to cache and how long to ensure security, data accuracy, and timeliness.</p></blockquote>



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



<p>Apollo Server enables you to define cache-control settings (<code>maxAge</code> and <code>scope</code>) for each field in your schema with the <code>@cacheControl</code> directive.</p>



<p>When Apollo Server resolves an operation, it calculates the correct cache behavior based on the most restrictive settings among the results&#8217; fields. Whenever Apollo Server sends an operation response with a non-zero <code>maxAge</code>, it includes a <code>Cache-Control</code> HTTP header describing the response&#8217;s cache policy.</p>



<p>If you run Apollo Server behind a CDN or another caching proxy, you can configure it to use this header&#8217;s value to cache responses appropriately.</p>



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



<p>Suppose you need to send <code>GET</code> requests because you can&#8217;t configure your edge caching to support cache hints for <code>POST</code> requests. In that case, you can also use automatic persisted queries (APQ) to create a unique hash for each query after the first request and then use <code>GET</code> requests with the hash for all future requests, allowing them to be cached by a CDN service.</p>



<p>Automatic persisted queries are supported by both Apollo Server and Apollo Client and are enabled through the <code>persisted-queries</code> link on the client instance.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Check out the <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/apollo-server/performance/caching/" target="_blank">Apollo server documentation</a> for more on all things edge caching.</p></blockquote>



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



<p>GraphQL uses something called a <strong>schema</strong> to define the shape of the API. A schema is like a contract between the server and the client. The schema defines what data the clients can request or change, and the server returns that data to the client.</p>



<p>There are some approaches to building GraphQL APIs that closely tie the functionality of the API to the underlying data source, such as managed GraphQL solutions. They reduce the complexity of managing your API and data layer infrastructure, but often at the cost of auto-generating a schema.</p>



<p>However, by not using a managed solution and applying a schema-first design approach, you can structure your schema based on precisely the data the client application needs and not based on the underlying data source.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>For a more in-depth look at how GraphQL works under the hood, check out <a rel="noreferrer noopener" href="https://www.apollographql.com/blog/graphql/basics/journey-of-a-graphql-query/" target="_blank">The Journey of a GraphQL Query</a>.</p></blockquote>



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



<p>Typically when we think of scale, we think of requests per minute and response times, but performance is only one part of scaling a technology. With the emergence of cloud computing and cloud providers offering various solutions for scaling servers horizontally and vertically, scale becomes more of a conversation about scaling the communication and collaboration around what the API should provide.</p>



<p>We&#8217;ve seen companies like Netflix, Walmart, PayPal, and others across every industry adopt GraphQL, but why?</p>



<p>Because while the technical benefits like performance gains from fewer requests and over-fetching of data initially drive GraphQL adoption, it quickly becomes clear that the developer experience and business intelligence benefits are the actual value of GraphQL.</p>



<p>As Mark Stuart states in their article &#8220;<a href="https://medium.com/paypal-tech/scaling-graphql-at-paypal-b5b5ac098810">Scaling GraphQL at PayPal</a>,&#8221; GraphQL is friendly to humans. With GraphQL, people think in terms of fields, entities, and relationships, not in endpoints and complex joins. The focus on client needs also ensures the API directly reflects business needs as client needs equal business needs.</p>



<p>GraphQL, despite the name, isn&#8217;t simply a query language. Instead, it&#8217;s a comprehensive solution to the problem of connecting modern apps to services in the cloud. It forms the basis for a new and vital layer in the modern application development stack: <strong>the graph</strong>.</p>



<p>The graph brings all of a company&#8217;s data and services together with one consistent, secure, and discoverable interface so that anyone can draw upon it with minimal friction.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>If you&#8217;d like to know more about scaling the graph, check out our graph best practices guide, <a rel="noreferrer noopener" href="https://principledgraphql.com/" target="_blank">Principled GraphQL</a>, and this post about <a rel="noreferrer noopener" href="https://www.apollographql.com/blog/backend/architecture/the-evolution-of-graphql-at-scale/" target="_blank">The Evolution of GraphQL at Scale</a>.</p></blockquote>



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



<p>Inversely, GraphQL provides a lot of developer experience improvements that benefit any team, no matter the size. For example, we all know that iteration speed is equally important whether you&#8217;re one person building your first app or part of a team working on a massive API. Sunil Pai <a href="https://twitter.com/threepointone/status/1449736965537075201">recently tweeted</a> asking which vectors people prioritize and more than half chose &#8220;Iterable&#8221;.</p>



<p>GraphQL enables many new tools, communication channels, and operational checks that allow teams of all sizes to benefit from adopting it. Here is a non-exhaustive list of benefits of adopting GraphQL that apply to a team or teams of any size:</p>



<ul class="wp-block-list"><li>Complexity moves back to the server, which allows clients to be slimmer and loosely coupled.</li><li>Data is more discoverable to developers and Product Managers, QA, or anyone else who might want to understand the business&#8217;s full digital capabilities.</li><li>Deeper insights into API usage allow for better observability and tight integration into CI/CD workflows by adding operational checks, preventing breaking changes.</li><li>Federated architectures allow backing services to scale independently based on usage and encourage fault tolerance on subsystems.</li><li>Smoother API evolution. Rather than releasing a new &#8220;version&#8221; of the graph periodically — such as every 6 or 12 months — you make changes to it many times a day if necessary. Contributors can add new fields at any time. To remove a field, it is first deprecated with the <code>@deprecated</code> directive and then removed when no consumers use it.</li><li>You can adopt GraphQL gradually. Many companies start by only running a few operations through the new GraphQL API, adding new functionality as they get more buy-in. This allows your graph to evolve naturally.</li></ul>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Check out the docs for more detail on the <a rel="noreferrer noopener" href="https://www.apollographql.com/docs/intro/benefits/" target="_blank">benefits and trade-offs of adopting GraphQL</a>.</p></blockquote>



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



<p>GraphQL is a production-ready technology that offers many developer experience benefits to single developers and large companies alike. However, while GraphQL has many benefits, it differs fundamentally from REST and can cause FUD among developers over specific topics, especially security and caching.</p>



<p>When adopting GraphQL, it&#8217;s best to use a client-driven approach to designing your API and remember that a schema is a contract between the client and server. The schema defines what data the clients can request or change, and the server returns that data to the client.</p>



<p>GraphQL, despite the name, isn&#8217;t simply a query language. Instead, it&#8217;s a comprehensive solution to the problem of connecting modern apps to services in the cloud. It forms the basis for a new and vital layer in the modern application development stack: <strong>the graph</strong>.</p>



<p>The graph brings all of a company&#8217;s data and services together, with one consistent, secure, and discoverable interface so that anyone can draw upon it with minimal friction.</p>


Demystifying GraphQL Misconceptions | Top Five GraphQL Myths Debunked

Using GraphQL with Golang

Journey of a GraphQL query


<p>When I first started learning about GraphQL, I thought that I needed a special tool to make GraphQL requests. Luckily, you don&#8217;t!</p>



<p>While we recommend using Apollo Studio&#8217;s <a href="https://www.apollographql.com/blog/announcement/platform/apollo-sandbox-an-open-graphql-ide-for-local-development/">Sandbox</a>, since GraphQL runs on top of HTTP, it&#8217;s possible to make GraphQL requests using any of the tools you were accustomed to using building out your apps with REST.</p>



<p>In this post, we&#8217;ll learn how to make GraphQL requests over HTTP with just GET and POST methods. We&#8217;ll also discuss the limitations of each approach.</p>



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



<ul class="wp-block-list"><li>You know <a href="https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/">what GraphQL is</a></li><li>You know <a href="https://www.apollographql.com/blog/graphql/basics/mutation-vs-query-when-to-use-graphql-mutation/">the difference between a query and a mutation</a></li><li>You&#8217;re familiar with <a href="https://www.apollographql.com/docs/apollo-server/getting-started/">the basics of Apollo Server</a> and have completed the getting started guide</li></ul>



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



<p>Let&#8217;s assume we have a basic Apollo Server that returns a greeting with an optional <code>name</code> variable:</p>



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

const resolvers = {
  Query: {
    hello: (_, args) =&gt; {
      let value;
      if (args.name) {
        value = `Hello ${args.name}, nice to meet you!`
      } else {
        value = `Hello, nice to meet you!`
      }
      return { value }
    }
  }
}

const typeDefs = gql`
  type Hello {
    value: String
  }

  type Query {
    hello(name: String): Hello
  }
`

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

server.listen().then(({ port }) =&gt; {
  console.log(`Server started on port: ${port}`)
})
﻿</code></pre>



<p>Apollo Server accepts either POST or GET HTTP methods as GraphQL requests. Let&#8217;s start with the POST method.</p>



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



<p>To make a GraphQL request using the POST HTTP method, we pass the following properties into the JSON body of the request.</p>



<ul class="wp-block-list"><li><code>query</code> — the full <a href="https://www.apollographql.com/blog/graphql/basics/the-anatomy-of-a-graphql-query/">GraphQL query</a> containing the operation type (can be either <code>query</code> or <code>mutation</code>), the types &amp; fields requested, and any variables included</li><li><code>operationName</code> — optional, but if included, <em>must</em> be present in the <code>query</code></li><li><code>variables</code> — optional <em>if</em> there are no variables included in the <code>query</code></li></ul>



<p>Here&#8217;s an example of a GraphQL request including an <code>operationName</code> and <code>variables</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;query&quot;: &quot;query GreetingQuery ($arg1: String) { hello (name: $arg1) { value } }&quot;,
  &quot;operationName&quot;: &quot;GreetingQuery&quot;,
  &quot;variables&quot;: { &quot;arg1&quot;: &quot;Timothy&quot; }
}</code></pre>



<p>We&#8217;d expect to see a response like the following:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
    &quot;data&quot;: {
        &quot;hello&quot;: {
            &quot;value&quot;: &quot;Hello Timothy, nice to meet you!&quot;
        }
    }
}</code></pre>



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



<p>You can also make GraphQL requests using the GET HTTP method. The rules for making GraphQL requests this way are almost the same as the POST version — there are just slight differences:</p>



<ul class="wp-block-list"><li>Each property is provided as an HTTP query parameter (values separated by an ampersand — <code>&amp;</code>)</li><li><strong>Limitation (variables):</strong> Because they need to be parsed as JSON, GraphQL requests with variables don&#8217;t work in GET requests.</li><li><strong>Limitation (operations)</strong>: You can only execute <code>query</code> operations (<code>mutation</code> operations don&#8217;t work)</li></ul>



<p>That said, the following request works nicely!</p>



<pre class="wp-block-code"><code>GET http://localhost:4000/?query=query GreetingQuery { hello { value } }&amp;operationName=GreetingQuery</code></pre>



<p>Which, when encoded for the web, looks like:</p>



<pre class="wp-block-code"><code>GET http://localhost:4000/?query=query%20GreetingQuery%20{%20hello%20{%20value%20}%20}&amp;operationName=GreetingQuery</code></pre>



<p>We could expect a response like the following.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
    &quot;data&quot;: {
        &quot;hello&quot;: {
            &quot;value&quot;: &quot;Hello, nice to meet you!&quot;
        }
    }
}</code></pre>



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



<p>In this post, we discussed how you can use HTTP GET and POST methods to send GraphQL requests. We also looked at some of the nuances and limitations of each approach.</p>



<p>If you&#8217;re just getting started with Apollo Server, you&#8217;ll see a screen similar to the following when you visit your running server in the browser.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="962" src="https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-1024x962.png" alt="" class="wp-image-8880" srcset="https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-1024x962.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-300x282.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-768x721.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-1536x1442.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-2048x1923.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-1200x1127.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-19-at-3.00.48-PM-1980x1859.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Clicking &#8220;Query your server&#8221; takes you to Apollo Studio&#8217;s sandbox and gives you an environment where you can quickly navigate and test out your GraphQL server. While you can use other tools, we recommend Sandbox as the best way to get started.</p>



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



<p>For demonstrations of other ways to make GraphQL requests, read &#8220;<a href="https://www.apollographql.com/blog/graphql/examples/4-simple-ways-to-call-a-graphql-api/">4 Simple ways to Call a GraphQL API</a>&#8220;.</p>



<p>For more on sending GraphQL requests with HTTP, read &#8220;<a href="https://www.apollographql.com/docs/apollo-server/requests/">POST and GET format — How to send requests to Apollo Server over HTTP</a>&#8221; from the official Apollo Server docs.</p>


Making GraphQL Requests using HTTP Methods


<p>How confident are you that changes to your API won&#8217;t break any clients? Not having confidence in knowing what could break when you release changes to your graph can grind teams to a halt and cause all sorts of problems for clients consuming your graph.</p>



<p>In this article, we&#8217;ll look at how adopting a DevOps culture can help you evolve your graph faster, improve communication around your data graph, as well as the role Apollo plays in achieving a DevOps workflow for your data graph.</p>



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



<p>DevOps is a set of practices that combines software development and IT operations. It aims to shorten the systems development life cycle and provide continuous delivery with high software quality. DevOps shares a lot of principles with Agile software development.</p>



<p>Implementing DevOps is not just about tools; it is also about how people work and the processes they use. DevOps is about unifying the engineering teams responsible for running an application or service in production.</p>



<p>Ideally, one team manages all aspects of the service, including security and testing functions. In larger organizations, there may still be some functional specialization. Still, it remains critical that the process and communication focus on the end-to-end delivery of the entire service.</p>



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



<p>One of the major benefits of adopting GraphQL is the ability to gradually evolve your API over time instead of being locked into versioning and large releases. However, as with all things, there&#8217;s an associated cost. Because it&#8217;s not a large coordinated effort to release changes to a graph, it&#8217;s pretty easy to change or remove a type or field that will break one or more clients.</p>



<p>Communication between everyone who consumes and maintains the graph can break down as your graph grows. To consistently meet clients&#8217; needs, we need to evolve a graph gradually, but we want to be able to do so quickly and reliably.</p>



<p>By adopting a DevOps culture and blending operations with development, we can greatly improve communication around a data graph. Improved communication leads to shorter feedback loops, fewer errors, and faster deployments.</p>



<p>Under a DevOps model, development and operations are no longer “siloed.” Instead, graph usage data is used in the build, test, and planning phases of a graph&#8217;s lifecycle.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="317" src="https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7-1024x317.png" alt="" class="wp-image-7712" srcset="https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7-1024x317.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7-300x93.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7-768x238.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7-1536x475.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7-1200x371.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-7.png 1564w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>At Apollo, we believe that data graphs are the epicenter of communication for teams and companies that adopt GraphQL. It&#8217;s why we&#8217;ve invested so heavily in creating the tooling needed to set up DevOps best practices for GraphQL APIs. Apollo provides a platform on top of a schema registry that works together to help you at each stage in the DevOps lifecycle.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="432" src="https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-6-1024x432.png" alt="" class="wp-image-7715" srcset="https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-6-1024x432.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-6-300x127.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-6-768x324.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-6-1200x506.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/06/build-test-release-6.png 1432w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



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



<p>Apollo offers various tools to help you develop your API faster. From Apollo Explorer, a <a href="https://github.com/apollographql">cloud-based GraphQL IDE</a> specifically tailored to GraphQL developers, to <a href="https://github.com/apollographql">numerous open-source libraries</a>, Apollo is deeply invested in helping developers build data graphs faster.</p>



<p>When developing locally, you can <a href="https://www.apollographql.com/blog/announcement/platform/apollo-studio-a-graphql-ide-for-every-environment/">use development graphs</a>, which enables you to use all of Apollo Explorer’s powerful features (like intelligent search and variable extraction) with your locally running GraphQL server.</p>



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



<p><a href="https://www.apollographql.com/docs/studio/schema-checks/">Schema checks in Apollo Studio</a> help you collaborate on your graph with confidence. Checks validate your schema changes against historical operations to ensure changes will not break existing clients.</p>



<p>For federated graphs, we also understand how important it is to have visibility of your graph’s composition. That&#8217;s why <a href="https://www.apollographql.com/blog/announcement/build-checks-webhooks-apollo-studio/">we&#8217;ve introduced build checks and webhooks</a> to help you better understand the impact of schema changes, update your data graph faster, and allow more teams to contribute to the graph safely.</p>



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



<p>Our new <a href="https://www.apollographql.com/docs/rover/">Rover CLI</a> helps you safely publish and fetch GraphQL schemas (monolithic and federated) from the Apollo schema registry. It is the successor to the Apollo CLI as the primary command-line tool for working with graphs.</p>



<p>When it comes to deploying federated graphs, Apollo provides <a href="https://www.apollographql.com/docs/federation/managed-federation/overview/">managed federation</a>. With managed federation, your&nbsp;gateway&nbsp;is no longer responsible for fetching schemas from your&nbsp;subgraphs&nbsp;on startup. Instead, your subgraphs push their schemas to the Apollo schema registry, verifying that they successfully&nbsp;compose&nbsp;into a federated schema. Studio then updates your graph&#8217;s latest configuration on composition success and makes your changes available to your gateway.</p>



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



<p><a href="https://www.apollographql.com/studio/observe/">Apollo Studio&#8217;s observability features</a> give you insight into every way your graph is being used and helps you find what’s wrong, what’s new, or what’s recently changed and take action.</p>



<p><strong>Tracing &#8211;</strong> Automatically trace your operation’s resolvers, even across federated services, with no added configuration in Apollo Server. Visualize how your resolvers execute, identify bottlenecks, track headers and variables associated with your requests, and more.</p>



<p><strong>Clients &#8211;</strong> <a href="https://www.apollographql.com/blog/announcement/platform/how-apollo-studio-client-awareness-improved-our-lives/">See precisely which clients are querying your graph</a> and what operations they’re sending — track changes to operations, performance degradations, and error spikes across client versions.</p>



<p><strong>Deprecations &#8211;</strong> Studio’s field-level usage tracking tells you precisely which of your clients last used each of your schemas fields, giving you the confidence to deprecate fields and sunset them without breaking any active usage of your graph.</p>



<p>Aside from observability around graph performance, Apollo Studio also provides a history of your schema, daily reports, and <a href="https://www.apollographql.com/docs/studio/schema-change-integration/">schema change notifications</a> to help keep you and your team(s) informed.</p>



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



<p>With Apollo Studio, you can view everything about your graph in one place – what data types exist, their documentation and interrelationships, the services that implement them, who are using them, when they last changed, when they last changed, and explore your graph with Apollo Explorer.</p>



<p>When it comes to scaling beyond a single graph, <a href="https://marketplace.visualstudio.com/items?itemName=apollographql.apollo-workbench">Workbench</a> can help you design a federated graph from the comfort of your editor without changing code or running servers.</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>Adopting a DevOps culture provides your team(s) with the safety, trust, and agency needed to ship changes to your data graph quickly and reliably. Apollo provides an extensive platform that helps GraphQL API developers put DevOps best practices in place by providing CI/CD and observability for your graphs.</p>



<p>To get started with Apollo Studio, head to <a href="http://studio.apollographql.com/dev">studio.apollographql.com/dev</a>.</p>


DevOps for GraphQL APIs – Build, Manage, and Scale the Graph


<p>Whether you&#8217;re just getting started with building GraphQL applications or you&#8217;ve done it for years, you probably have a decent understanding of&nbsp;<a target="_blank" href="https://www.apollographql.com/blog/what-is-a-graphql-query-graphql-query-examples-using-apollo-explorer/" rel="noreferrer noopener">what GraphQL queries are</a>. But what about GraphQL fragments?&nbsp;</p>



<p>&nbsp;In this article, we&#8217;ll delve into some common use-cases where fragments shine, learn how to get the most out of them, and hopefully, I&#8217;ll inspire you to use more fragments in your GraphQL queries.</p>



<h2 class="wp-block-heading"><a href="#use-case-modeling-a-list" aria-hidden="true" class="aal_anchor" id="use-case-modeling-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>Use case: modeling a list</h2>



<p>When you build a GraphQL-based application, the typical choice pattern is to start with building components — brilliantly simple UI components — that declare their data needs of which you can fetch using GraphQL queries. After a few data loading wins, you&#8217;re ready for something a little bit more complex — the infamous <em>List</em> component. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">export function SimpleGroceryList() {
  const { data } = useQuery(gql`
    query SimpleGroceryListQuery {
      groceries {
        id
        name
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;li key={grocery.id}&gt;
          {grocery.name}
        &lt;/li&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p>As shown above, we can write a single query that fetches the entire list, and for each item, we get back the id and name. Now, sometimes this is about all you need. Other times, though, rendering a list item is not so simple, and before long, we&#8217;re asking ourselves an age-old question:&nbsp;<em>should the list item be a separate componen</em>t?&nbsp;</p>



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



<p>We need to be aware of a tipping point here. When the complexity of the markup begins to hurt your head, keeping a stronger separation of concerns can be hugely beneficial (this doesn&#8217;t just apply to lists, but also any parent/child relationship in your render tree). The example we present here as a demonstration is relatively light, but we&#8217;ve seen some pretty gnarly scenarios. Let&#8217;s refactor this into two components. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// item
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}

// list
export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        name
        quantity
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



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



<p>We might tolerate these two components sharing the same file at first, but as complexity scales up, it often becomes harder to maintain without refactoring GroceryListItem into its own file.&nbsp;</p>



<p> We now have GroceryListItem.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryListItem.jsx
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}</code></pre>



<p>And we have the cleaner GroceryList component as well.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryList.jsx
export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        name
        quantity
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p>While this separation of the parent and child component reduces clutter, it comes with two slight disadvantages we need to address.</p>



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



<p>Once we split the files apart, we lose the ability to scan the GraphQL query and compare it with the usage of the data in our UI code. So what can we do?&nbsp;</p>



<p> In the early days of React, to clarify the data dependencies of GroceryListItem, we might try addressing this with “PropTypes”. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryListItem.jsx
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}

// re-describe our component&#039;s data dependencies
GroceryItemList.propTypes = {
  grocery: PropTypes.shape({
    name: PropTypes.string.isRequired,
    quantity: PropTypes.number.isRequired,
  }).isRequired,
};</code></pre>



<p>PropTypes work, but it also exposes another disadvantage: duplicating data dependencies.</p>



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



<p>Regardless of if you&#8217;re using PropTypes or TypeScript to define component props, we still have a lot of typing to do. We&#8217;re duplicating the shape of our component&#8217;s data in two places: first in the GraphQL query and again in the component&#8217;s property list, which indeed makes fingers tired.</p>



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



<p>At their core,&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/react/data/fragments/" rel="noreferrer noopener">GraphQL fragments</a>&nbsp;are just small pieces (or &#8220;fragments&#8221;) of a larger GraphQL query. But how can they help us in this situation?</p>



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



<p>With fragments, we can bring back the benefits of co-locating our data dependencies with our UI code, but in a more distributed way across the application. In the following code, we define a fragment with only the data that we need and export it for inclusion in the parent query. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryItemList.tsx

export const groceryListItemFragment = gql`
  fragment GroceryListItemFragment on Grocery {
    name
    quantity
  }
`;

/**
 * Automatically generated fragment type (you don&#039;t have to type this!)
 *
export interface GroceryListItemFragment {
  name: string;
  quantity: number;
}
*/

interface Props {
  grocery: GroceryListItemGroceryFragment;
}

export function GroceryListItem({ grocery }: Props) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}</code></pre>



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



<p>Not only do fragments act as a way to express data dependencies, but&nbsp;<a target="_blank" href="https://www.apollographql.com/blog/tooling/apollo-codegen/typescript-graphql-code-generator-generate-graphql-types/" rel="noreferrer noopener">using Apollo codegen</a>, we can type the data dependencies once and auto-generate Typescript types to ensure we pass the exact shape of data we need.&nbsp;</p>



<h3 class="wp-block-heading"><a href="#detect-breaking-api-changes" aria-hidden="true" class="aal_anchor" id="detect-breaking-api-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>Detect breaking API changes</h3>



<p>We automatically generate typings using the schema from our GraphQL API.&nbsp;</p>



<p>If we take advantage of a schema repository like the one provided through Apollo Studio, we can generate your types for our queries against whichever graph variant you need.&nbsp;</p>



<p>The auto-generated typings are useful because we can run `apollo codegen:generate` in the CI to ensure that all of the queries and fragments we&#8217;re requesting are available in the API when the code goes live.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="570" height="696" src="https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks.png" alt="" class="wp-image-7539" srcset="https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks.png 570w, https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks-246x300.png 246w" sizes="auto, (max-width: 570px) 100vw, 570px" /></figure>



<p>To get started with&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/studio/schema-checks/" rel="noreferrer noopener">schema checks</a>&nbsp;and several other free GraphQL tools to help you build better, safer, and faster, register your graph @&nbsp;<a target="_blank" href="https://studio.apollographql.com/dev" rel="noreferrer noopener">https://studio.apollographql.com/dev</a>.</p>



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



<p>Going back to our example, in the parent list component, we import the fragment into our query and fetch the data for each grocery item as before.&nbsp;</p>



<p>Notice that we also request the id field in addition to GroceryListItemFragment , clarifying that GroceryList has a dependency on id but no other fields.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryList.tsx

import { groceryListItemFragment, GroceryListItem } from &#039;./GroceryListItem&#039;;

export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        ...GroceryListItemFragment // fragment is &quot;spread&quot; here
      }
    }
    ${groceryListItemFragment} // also include the fragment definition in the query
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p>Nice! What happens if we decide to add another piece of information to the list item? We modify our fragment definition, re-run code generation, and voila — and we have updated our strong types. We&#8217;ve also maintained the separation of concerns between fetching the list and describing how we render an item.</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 we started building&nbsp;<a target="_blank" href="https://studio.apollographql.com/dev" rel="noreferrer noopener">Apollo Studio&#8217;s</a>&nbsp;frontend application, it was way back in the early days of React 14. We were making heavy use of GraphQL but still figuring out best practices. As our codebase began to expand in scope and complexity, we started to develop more scalable patterns and developed many new strategies for weaving together GraphQL, Typescript, and UI functionality. Some of the big lessons were the many benefits that fragments provide:</p>



<ul class="wp-block-list"><li>Declaring fragments alongside UI code allows you to separate concerns between parent components and children.</li><li>Defining and exporting fragments makes components more re-usable since data dependencies are expressively declared, and parents can compose as needed.</li><li>Using fragments allows you to make a single query to fetch data for multiple components at once, reducing the need for repeated round-trips to the server.</li><li>Automatic type generation FTW. Strict build-time checking prevents bugs before they happen; codegen eliminates duplication of code to describe data shapes across the component boundary.</li></ul>



<p>Hopefully, this helps solve some problems that you might have in your codebase. Thanks for reading!</p>


Using GraphQL Fragments for safer, cleaner, and faster code

9 Ways To Secure your GraphQL API — GraphQL Security Checklist

Why You Should Disable GraphQL Introspection In Production – GraphQL Security


<p>GraphQL is first and foremost: a query language. It&#8217;s a more flexible and robust way to ask for data. You can use JavaScript to execute GraphQL anywhere. In this short post, we&#8217;ll take a look at the underlying JavaScript GraphQL implementation used by many popular GraphQL libraries and frameworks: <code>graphql-js</code>.</p>



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



<ul class="wp-block-list"><li>You <a href="https://www.apollographql.com/blog/what-is-graphql-graphql-introduction/">understand what GraphQL is</a></li><li>You&#8217;re familiar with the command line</li><li>You have Node.js (8+) installed</li></ul>



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



<p><a href="https://github.com/graphql/graphql-js">GraphQL.js</a> is the <em>reference implementation</em> of GraphQL for JavaScript. By <em>reference implementation</em>, we mean that it adheres to the rules declared in the official <a href="https://spec.graphql.org/June2018/">GraphQL specification</a>.</p>



<p>Other languages have also implemented the GraphQL specification, like <a href="https://github.com/graphql-java/graphql-java">Java</a>, .<a href="https://github.com/graphql-dotnet/graphql-dotnet">NET</a>, and <a href="https://github.com/graphql-go/graphql">Go</a>.</p>



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



<p>Let&#8217;s install GraphQL.js and execute a query with it.</p>



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



<p>We&#8217;ll start by creating a new folder for our project. Run the following command to create a directory and then <code>cd</code> into it.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">mkdir graphql-js
cd graphql-js</code></pre>



<p>Use <code>npm</code> (or Yarn) to initialize a new Node.js project.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">npm init --yes</code></pre>



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



<p>To install <code>graphql-js</code>, run the following command:</p>



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



<p>This should create a <code>package.json</code> file and a <code>node_modules</code> folder. Next, we&#8217;ll create the file that we&#8217;re going to work within.</p>



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



<p>We&#8217;ll write our code in a single file. Create a new <code>index.js</code> file in the current directory.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">touch index.js</code></pre>



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



<p>The following code constructs a schema with the root <code>Query</code> type containing a <code>hello</code> field. Then, we create a resolver to resolve the value for the <code>hello</code> field and run a query by passing in the schema, the query <em>itself</em>, and graph resolvers.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const { graphql, buildSchema } = require(&#039;graphql&#039;);

// Builds a schema using the GraphQL schema language
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// The root of our graph gives us access to resolvers for each type and field
const resolversRoot = {
  hello: () =&gt; {
    return &#039;Hello world!&#039;;
  },
};

// Run a simple graphql query &#039;{ hello }&#039; and then print the response
graphql(schema, &#039;{ hello }&#039;, resolversRoot).then((response) =&gt; {
  console.log(JSON.stringify(response.data));
});</code></pre>



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



<p>To run this code, in your console — type the following command:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-bash">node index.js</code></pre>



<p>If all goes well, you should see this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{ &quot;hello&quot;: &quot;Hello world!&quot; }</code></pre>



<p>This is how we can use plain JavaScript to write GraphQL queries with GraphQL.js.</p>



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



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



<p>GraphQL.js is the definitive JavaScript GraphQL implementation, but most of us are using GraphQL to build backend APIs. For that to work, we need to serve GraphQL over HTTP.</p>



<p>We covered how GraphQL.js works (under the hood of other GraphQL JavaScript libraries like Apollo Server), but I recommend reading &#8220;<a href="https://www.apollographql.com/blog/using-express-with-graphql-server-node-js/">Using Express with GraphQL – How to create a GraphQL server with Node.js/Express</a>&#8221; to learn how to connect GraphQL to a web server.</p>


How to use GraphQL with Javascript – GraphQL.js tutorial


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p>This post is part of the Introduction to GraphQL series. You may want to read the previous posts: &#8220;<a rel="noreferrer noopener" href="https://www.apollographql.com/blog/what-is-graphql-graphql-introduction/" target="_blank">What is GraphQL? GraphQL introduction</a>&#8221; and &#8220;<a rel="noreferrer noopener" href="https://www.apollographql.com/blog/what-is-a-graphql-query-graphql-query-examples-using-apollo-explorer/" target="_blank">What is a GraphQL Query? GraphQL query examples using Apollo Explorer</a>&#8220;</p>
</blockquote>



<p>So far, we&#8217;ve covered what GraphQL is: a <strong>query language</strong> and a <strong>server-side runtime</strong>. But more importantly, GraphQL is the modern way to build declarative, efficient and performant APIs that developers love to work with.</p>



<p>In <a href="https://www.apollographql.com/blog/what-is-a-graphql-query-graphql-query-examples-using-apollo-explorer/">the last post</a>, we learned about GraphQL queries and how to test querying your API with <a href="https://studio.apollographql.com/dev?referrer=blog">Apollo Explorer</a>. </p>



<p>In this post, we&#8217;re going to spend some more time on the <em>other </em>GraphQL operation: mutations. We&#8217;ll cover what mutations are, how they compare to queries, and when to use them.</p>



<h2 class="wp-block-heading"><a href="#about-graphql-mutations" aria-hidden="true" class="aal_anchor" id="about-graphql-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>About GraphQL mutations</h2>



<p>In GraphQL, there are only two types of operations you can perform: queries and <strong>mutations</strong>.</p>



<p>While we use queries to fetch data, we use <strong>mutations to modify server-side data</strong>.</p>



<p>If queries are the GraphQL equivalent to <code>GET</code> calls in REST, then mutations represent the state-changing methods in REST (like <code>DELETE</code>, <code>PUT</code>, <code>PATCH</code>, etc).</p>



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



<p>Consider a <em>pet shop</em> GraphQL API.</p>



<p>A <code>query</code> to fetch all the pets from the app might look like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetAllPets {
  pets {
    name
    petType
  }
}</code></pre>



<p>And then a <code>mutation</code> that adds a new pet might look a little something like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation AddNewPet ($name: String!, $petType: PetType) {
  addPet(name: $name, petType: $petType) {
    id
    name
    petType
  }
}</code></pre>



<p>The <code>AddNewPet</code> <code>mutation</code> expects values for the <code>name</code> and <code>petType</code> variables. The request data for this <code>mutation</code> holds the following shape. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;name&quot;: &quot;Rover&quot;,
  &quot;petType&quot;: &quot;DOG&quot;
}</code></pre>



<p>In the <code>mutation</code> response, you could expect to see the following result. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;data&quot;: {
    &quot;addPet&quot;: {
      &quot;id&quot;: 1
      &quot;name&quot;: &quot;Rover&quot;,
      &quot;petType&quot;: &quot;DOG&quot;
    }
  }
}</code></pre>



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



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



<p>Mutations look very similar to queries. If you&#8217;ll recall, the general structure of a GraphQL operation looks like this.</p>



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



<p>One <em>true</em> difference between a query and a mutation, at least <em>structurally</em>, is the <strong>operation type</strong>. We use the word <code>query</code> for queries and <code>mutation</code> for mutations.</p>



<p>Another important thing to note is that we signal the <code>mutation</code> we want to invoke by naming it exactly as it occurs within our server-side GraphQL API.</p>



<p>In the <code>AddNewPet</code> example, the name of the mutation is <code>addPet</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation AddNewPet ($name: String!, $petType: PetType) { 
  addPet(name: $name, petType: $petType) { # mutation name
    name
    petType
  }
}</code></pre>



<p>This means that within our GraphQL API type definitions, we&#8217;d have a field on the root Mutation object that looks like the following:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Mutation {
  addPet (name: String!, petType: PetType): AddPetResult!
}</code></pre>



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



<p>Server-side resolvers for <code>mutations</code> involve code that changes state in some way. </p>



<p>Here&#8217;s an example of what it might look like to add a new pet using a connection to a <code>petsAPI</code> <a href="https://www.apollographql.com/docs/apollo-server/data/data-sources/">data source</a>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const resolvers = {
  ...
  Mutation: {
    addPet: async (root, args, context) =&gt; {
      const { name, petType } = args;
      const newPet = await context.dataSources.petsAPI.addPet({ name, petType })
      return {
        id: newPet.id,
        name,
        petType
      }
    }
  }
};</code></pre>



<p>Compare this to a resolver in a <code>query</code> where the only responsibility is to fetch the requested resource.</p>



<p>Again, like RESTful requests, there&#8217;s nothing stopping us from writing API code here that makes the <code>mutation</code> resolver behave more like a <code>query</code>. But by convention, we ensure <code>mutation</code> operations change state, and <code>query</code> operations fetch data. </p>



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



<p>You may have noticed that the <code>mutation</code> also returns data; this is another similarity between queries and mutations. However, it&#8217;s conventional to only return the relevant new data that was created.</p>



<h2 class="wp-block-heading"><a href="#conclusion-determining-whether-to-use-query-or-a-mutation" aria-hidden="true" class="aal_anchor" id="conclusion-determining-whether-to-use-query-or-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>Conclusion: Determining whether to use query or a mutation</h2>



<p>The best way to determine whether you want to write a query or a mutation is to ask yourself if you&#8217;re <strong>fetching data</strong> (<code>query</code>) or if <strong>modifying state in the server</strong> (<code>mutation</code>).</p>



<p>More query examples:</p>



<ul class="wp-block-list">
<li><code>GetPetByPetId</code>, <code>GetMyPets</code>, <code>GetPetStores</code></li>
</ul>



<p>More mutation examples:</p>



<ul class="wp-block-list">
<li><code>EditPet</code>, <code>RemovePet</code>, <code>GiveTreat</code>, <code>RemoveAllPets</code>, <code>Login</code>, <code>Logout</code></li>
</ul>



<p></p>


GraphQL Mutation vs Query – When to use a GraphQL Mutation

What is GraphQL? GraphQL introduction


<p>Before there was GraphQL, there was REST.</p>



<p>In recent years, REST has become the dominant API style for building backend web services. With REST, you could signal the <em>type</em> of request we want to make (ex: GET, POST, PUT, or DELETE) and the resource we&#8217;d like to fetch or interact with (ex: /api/pets/1) using an HTTP method and a URL.</p>



<p>It&#8217;s a great approach (and one we initially used at StockX for several years). But REST comes with some downsides like:</p>



<ul class="wp-block-list"><li>Over-fetching</li><li>Multiple requests for multiple resources</li><li>Waterfall network requests on nested data</li><li>Each client need to know the location of each service</li></ul>



<p>Then came GraphQL: <em>a server-side runtime and query language for your API</em>.</p>



<figure class="wp-block-image"><img decoding="async" src="https://lh3.googleusercontent.com/oj_FXuoy-dgivuMUSvl77tMfB4GmCZfoNjlNSdPtbZZqbiPPQGxECvEGwHDSONvniQTI2Gw9rtFIvm-DIepa1oN5xZcWKerJYdf7v8LOACGxofTYC4mnTeI65Q3INYqXv3r61us5" alt=""/></figure>



<p>GraphQL lets you ask for what you want in a single query, saving bandwidth and reducing waterfall requests. It also enables clients to request their own unique data specifications.</p>



<p>In the summer of 2019, I wanted to make a case to migrate from our existing RESTful API architecture to GraphQL at StockX. Since then, we&#8217;ve been running GraphQL in production and enjoying the benefits around topics like documentation, performance, and developer productivity.</p>



<p>In this blog post, we&#8217;ll touch upon seven of the most notable benefits of GraphQL taken from my original 16-page RFC (request for comments) that we used to make the decision to switch from REST to GraphQL.</p>



<h2 class="wp-block-heading" id="no-more-versioned-apis"><a href="#no-more-versioned-apis" aria-hidden="true" class="aal_anchor" id="no-more-versioned-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><a href="https://kyleschrade-blog.netlify.app/posts/why-use-graphql#no-more-versioned-apis"></a>No more versioned APIs</h2>



<p>In a RESTful world, APIs have versions, and as APIs evolve, API version numbers increase. And as long as services keep on improving, version numbers never stop incrementing.</p>



<p>This leads to problems down the line.</p>



<p>For example, when version numbers increase indefinitely, it becomes challenging to know the latest API version capable of returning the correct data.</p>



<p>This also leads to the confusion of having multiple versions for each environment (ex: perhaps example is in V1, staging is in V2, and production is in V3).</p>



<p>In GraphQL, there&#8217;s one version of the graph. To keep track of how the graph changes and evolves over time, we register it in a<a href="https://www.apollographql.com/docs/studio/schema/registry/"> schema registry.</a> The registry behaves similar to that of a version control system like Git, and becomes the central place that keeps track of the current state of the graph.</p>



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



<p>In RESTful API, there are no <em>partial</em> payloads — you get <em>everything</em> in every request, every time. If you don&#8217;t <em>need</em> everything, that&#8217;s unnecessary bandwidth.</p>



<p>In GraphQL, you specify the exact types and fields that you need; and if you don&#8217;t need much, that introduces the potential to make your API requests smaller. And for client-side applications that depend on data from APIs, reducing the amount of data transmitted could improve their performance considerably.</p>



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



<p>GraphQL has strictly-typed interfaces where REST APIs have much looser ones.</p>



<p>Let&#8217;s say the base URL for your RESTful API is <code>http://www.restful.com/api/v1</code>. If we wanted to add posts as a resource, we could represent that with <code>http://www.restful.com/api/v1/posts</code>.</p>



<p>Executing a GET request on this URL <em>should</em> return an array of posts, though, of course, there&#8217;s nothing stopping the server-side developers from returning something completely different. Ultimately, this approach works well up until the point where we start to add <a href="https://en.wikipedia.org/wiki/Query_string">query params</a>.</p>



<p>For example, if we wanted to include authors, we could adjust the route to accept another parameter to signal an additional resource type, like <code>api/v1/posts?include=author</code>.</p>



<p>How about the use case where we need to sort posts? The URL then becomes <code>api/v1/posts?include=author&amp;sort=ASC</code>. Hopefully, you can see that the more we continue to add query params to improve the functionality of the endpoint, the more unmanageable it becomes.</p>



<p>These challenges lead to questions like &#8220;what&#8217;s the correct path to use?&#8221; and &#8220;what are the valid params I can send, and how do I send them? &#8220;. If you have front end and back end teams, these query parameters can stay undocumented for a long time.</p>



<p>GraphQL solves this with a single endpoint and a strictly-typed schema. By design, the schema defines the resources available for retrieval in addition to the accepted parameters when fetching that data.</p>



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



<p>We already mentioned the ability to reduce payload size, but GraphQL also introduces the ability to minimize round trips to the server.</p>



<p>In a RESTful world, clients request a resource from the server, get the ID for it, then use that ID to fetch another resource (a waterfall-like series of requests to get related data).</p>



<p>GraphQL lets you get all the data you need in a single request; no need for follow-up requests.</p>



<h2 class="wp-block-heading" id="less-developer-time-spent-navigating-apis"><a href="#less-time-spent-documenting-and-navigating-apis" aria-hidden="true" class="aal_anchor" id="less-time-spent-documenting-and-navigating-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><a href="https://kyleschrade-blog.netlify.app/posts/why-use-graphql#less-developer-time-spent-navigating-apis"></a><strong>Less time spent documenting and navigating APIs</strong></h2>



<p>Traditionally, in RESTful API development, we&#8217;d use a tool like Swagger to document and navigate large APIs. I&#8217;ve found that Swagger docs are great on projects with a single service because everyone can pitch in to keep the documentation up to date. Once you get into the microservice world, however, documentation has the potential to become expensive to maintain. With Swagger docs scattered across multiple repos, it can be hard for new developers to ramp up.</p>



<p>GraphQL is already strictly-typed and declarative, so that&#8217;s an immediate improvement. But for what cannot be said declaratively through types and fields alone, we can also document the GraphQL schema. It looks like code comments and leads to being outwardly accessible.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Customer {
  &quot;&quot;
  ID is generated by the database
  &quot;&quot;
  id: ID!

  &quot;&quot;
  Customer name is pulled from the CRM
  &quot;&quot;
  name: String!

  &quot;&quot;
  The list of orders that belongs to the customer.
  &quot;&quot;
  orders: [Order]
}</code></pre>



<p>And again, this self-documenting schema coupled with 1 URL makes onboarding developers much more straightforward than sending them multiple swagger docs.</p>



<p>There are also some excellent tools to explore your graph, like <a href="https://www.apollographql.com/blog/introducing-the-apollo-explorer/">Apollo Studio&#8217;s Explorer</a>, <a href="https://github.com/graphql/graphql-playground">GraphQL Playground</a>, or <a href="https://github.com/graphql/graphiql">GraphiQL</a>.&nbsp;</p>



<h2 class="wp-block-heading" id="legacy-app-support"><a href="#legacy-app-support" aria-hidden="true" class="aal_anchor" id="legacy-app-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><a href="https://kyleschrade-blog.netlify.app/posts/why-use-graphql#legacy-app-support"></a><strong>Legacy app support</strong></h2>



<p>Upon releasing a RESTful API into the wild, it has to stay available for a long time. Depending on your company&#8217;s stance on legacy apps, that could be for as long as someone has that app. This means you can&#8217;t remove the V1 endpoints from your code no matter how out of date the endpoint is. It&#8217;s usually not a big deal until it is a massive problem. It can force you to keep older versions of packages, which might have security vulnerabilities or significantly increase the side of your build.</p>



<p>The other sizeable unexpected problem this causes is circumventing the new API. If V1 has different requirements than V2, it can wreak havoc on the backend when we add a resource with two different sets of required fields.</p>



<p>Since we typically only run a single GraphQL graph, when we swap out the graph&#8217;s data, that&#8217;s ok as long as the response looks the same. This allows people to swap out backends and change the source of truth on the backend with no changes from the front ends. And in addition to backends changing with no client changes, as long as the schema supports the query path, the legacy app will always be supported.</p>



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



<p>An area of typical complexity in traditional RESTful APIs is error handling. If any part of the code on a server fails during a request, that means the entire request fails; this can lead to code bloat and complex logic on front end applications when a microservice ecosystem fails.</p>



<p>To illustrate the complexity, consider the scenario where you have three subsequent REST calls that happen on a page. In the client-side code, you&#8217;d have to write the logic that dictates what happens when:</p>



<ul class="wp-block-list"><li>call one fails</li><li>call one passes&nbsp;</li><li>call two fails</li><li>and calls one and two pass but call three fails.</li></ul>



<p>GraphQL resolves as much data as it can before returning. It returns a top-level error object with an array of errors but still returns as much information as possible, allowing front ends to decide how to handle the partial data.</p>



<p>Think of a product page on <a href="http://amazon.com">amazon.com</a>. If a RESTful API backed it, how would the UI deal with partial failure, and how many partial failures would it have to deal with? If supported by GraphQL, we could check the error array to see if there is an error for the section it was about to display.</p>



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



<p>From performance, payload size, developer time, and built-in documentation, GraphQL is the future of APIs. This post covered seven of the tremendous benefits of GraphQL vs. REST.&nbsp;<br></p>



<p>If you&#8217;re just getting started with GraphQL and Apollo, check out the <a href="https://www.apollographql.com/docs/tutorial/introduction/">full-stack tutorial</a>. If you&#8217;re interested in learning more about how GraphQL can help you get more done faster in your company, download the free <a href="https://www.apollographql.com/guide/">GraphQL at Enterprise Scale</a> ebook by the Apollo team.</p>


Why use GraphQL?

Full Stack Error Handling with GraphQL and Apollo 🚀

Using nullability in GraphQL

Reusable GraphQL schema directives

GraphQL vs. REST

Tutorial: GraphQL Input Types and Custom Resolvers


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


GraphQL