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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


Using the GitHub GraphQL API with Apollo Studio Explorer


<p>Building schemas are a key part of building a graph. Schemas are one of the major benefits of using GraphQL. The schema defines how clients can retrieve and data from your GraphQL API. With schemas, you can easily shape and evolve your data to fit your specific business, product, or project needs. If you&#8217;re new to the GraphQL world, you might be wondering how you can build flexible and evolvable schemas.</p>



<p>In this article, we&#8217;ll go over some principles to keep in mind when designing your own GraphQL schema. Before getting started, here are a few things you should know:</p>



<ul class="wp-block-list"><li>You should know what GraphQL is. If you&#8217;re unclear on this check out this <a href="https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/">What Is GraphQL blog post</a>.</li><li>You know what a schema is and you&#8217;re familiar with Schema Definition Language (SDL). If you need to brush up on this, check out our <a href="https://www.apollographql.com/docs/apollo-server/schema/schema/">documentation on schema basics</a>.</li></ul>



<p>Once you&#8217;re more familiar with these topics, you&#8217;ll be fully prepared to dive into schema design and what you need to know to get started.</p>



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



<p>When thinking about the design of your schema, it&#8217;s important to know your domain well. You should be familiar with your application&#8217;s UI. You should also be familiar with the behavior of your users or intended audience.</p>



<p>For example, if you&#8217;re building an API for an education platform, you will want to know what the needs and behaviors are for the typical user or student. What information will they want to have access to? What information will they want to change? What data is absolutely required for both the users and you and your team (if you have one)? How will this data be displayed on your UI?</p>



<p>You should be asking yourself these questions to make sure you know your business domain well. Knowing this information will allow you to fully take advantage of the flexibility of GraphQL and in turn design an efficient and useful schema. When your domain is also your field of expertise, you can fully customize your schema to fit your needs well. If you don&#8217;t feel like you&#8217;ve reached the &#8220;field of expertise&#8221; level yet, start by asking yourself the questions mentioned above.</p>



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



<p>First off, what is a graph? One of the special things about GraphQL is that it changes how we view our data. Instead of viewing things in table form, which can be 2-dimensional, we can think of our data as a collection of objects and relationships between those objects.</p>



<p>We can take this a step further and call those objects <strong>nodes</strong> and the relationships that connect them <strong>edges.</strong> When you illustrate this structure either by hand or using some sort of illustration software, you&#8217;re left with a <strong>graph.</strong> How would this look with a real application?</p>



<p>Take a look at the UI for the education platform we mentioned earlier. This is the home page which will display courses along with the title, author name, and thumbnail for each course.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="672" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.26.06-AM-1024x672.png" alt="Course page mockup with several cards for each course which includes a thumbnail, title, and author name." class="wp-image-11425" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.26.06-AM-1024x672.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.26.06-AM-300x197.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.26.06-AM-768x504.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.26.06-AM-1200x787.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.26.06-AM.png 1290w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The UI mockup for our education platform example</figcaption></figure>



<p>We can make a direct connection between the information displayed for each course and the data we&#8217;ll need from our API.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="571" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.28.51-AM-1024x571.png" alt="An illustration that includes the mockup course card and a mapping of the data required for the card. This includes title, thumbnail, and author." class="wp-image-11423" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.28.51-AM-1024x571.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.28.51-AM-300x167.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.28.51-AM-768x428.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.28.51-AM-1200x669.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.28.51-AM.png 1280w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The data we&#8217;ll need to display for each course on our education platform home page</figcaption></figure>



<p>This can be translated into a graph that would look like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="569" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.35.00-AM-1024x569.png" alt="The graph for the data we need for the course mockup page." class="wp-image-11427" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.35.00-AM-1024x569.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.35.00-AM-300x167.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.35.00-AM-768x427.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.35.00-AM-1200x667.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-08-at-11.35.00-AM.png 1284w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>The graph representation of the data we need and the relationships between the data</figcaption></figure>



<p>With this graph in place, you can visualize the data and the relationships they share. Then this can be reflected in your schema.</p>



<pre class="wp-block-code"><code>type Query {
  &quot;Get tracks array for homepage grid&quot;
  tracksForHome: &#091;Track!]!
}
&quot;A track is a group of Modules that teaches about a specific topic&quot;
type Track {
  id: ID!
  &quot;The track&#039;s title&quot;
  title: String!
  &quot;The track&#039;s main author&quot;
  author: Author!
  &quot;The track&#039;s main illustration to display in track card or track page detail&quot;
  thumbnail: String
  &quot;The track&#039;s approximate length to complete, in minutes&quot;
  length: Int
  &quot;The number of modules this track contains&quot;
  modulesCount: Int
}
&quot;Author of a complete Track&quot;
type Author {
  id: ID!
  &quot;Author&#039;s first and last name&quot;
  name: String!
  &quot;Author&#039;s profile picture url&quot;
  photo: String
}
</code></pre>



<p><meta charset="utf-8"><strong>💡 If you would like a more in-depth explanation of how this schema was built, check out lessons 2-4 in the <a href="https://odyssey.apollographql.com/lift-off-part1">Odyssey Lift Off I course</a></strong></p>



<p>Mapping out your application&#8217;s graph is great because it helps you make the connection between your application&#8217;s UI and how users will interact with your data. These two things are very important when you&#8217;re designing your own schema because these things should be reflected in how your data is structured.</p>



<p>The key takeaway here is that your schema should mirror your graph. So mapping out your graph before you build your schema is a great habit to form. Try doing this when you’re building your first few schemas. It can even be helpful to draw out graphs for existing applications that you use every day. This will help you start “thinking in graph” aka thinking about data as a graph.</p>



<h2 class="wp-block-heading"><a href="#design-for-specific-use-cases" aria-hidden="true" class="aal_anchor" id="design-for-specific-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>Design for specific use cases</h2>



<p>Your schema will be accessible to front-end developers who are working with different UIs: mobile, desktop, smart TVs, and sometimes even smart watches! For each of these front-end clients, data might be displayed differently. This might cause you to try to be generic and create one-size-fits-all types and fields. But is this the best way to do things?</p>



<p>In software development, we typically want our code to be as concise as possible and everyone knows about the DRY rule (Don&#8217;t Repeat Yourself). But when designing your schema, you should be trying to accommodate client use cases, no matter how specific they are. Does this mean you should get rid of fields and types that are generic? No! You can be both generic AND specific.</p>



<p>What specific behaviors and use cases should you be accounting for? Well, the answer to this question comes with knowing your domain and users well. Keep in mind, too, that the specific use cases for your clients will change over time as your application grows. You might start out with a web app but eventually grow to include a mobile client. When your application evolves like this, so will your schema. So it&#8217;s good to adopt this use case and behavior-centric mindset now.</p>



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



<p>Naming things is hard but it&#8217;s a very important part of software development and that includes schema design. We sometimes default to using the easiest names to think of when creating types for our schema. But that can lead to confusion and breaking changes later on.</p>



<p>Let&#8217;s think about the education platform example mentioned earlier. Say we want to include reviews for courses and lessons. We might be inclined to create a type called <code>Review</code>. But we could be more specific. Using <code>CourseReview</code> and <code>LessonReview</code> as types instead of <code>Review</code> makes our code more clear and understandable. Going back to the previous point mentioned, it also allows us to build for specific use cases and user behaviors.</p>



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



<p>Now that you know these guiding principles for schema design, you can dive right into building your own schemas! If you want more information on building evolvable schemas that are built to be future-resistant, check out this article <a href="https://www.apollographql.com/blog/backend/schema-design/graphql-building-evolvable-schemas/">GraphQL Schema Design: Building Evolvable Schemas</a>.</p>



<p>I also highly recommend you check out our <a href="https://odyssey.apollographql.com/">GraphQL course, Odyssey</a>. The course covers building schemas and APIs in a beginner-friendly way and is a great way to take your GraphQL knowledge to the next level.</p>


Designing Your First GraphQL Schema


<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

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


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

Using nullability in GraphQL

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

Using the GitHub GraphQL API with Apollo Studio Explorer

Designing Your First GraphQL Schema

Demystifying GraphQL Misconceptions | Top Five GraphQL Myths Debunked

Journey of a GraphQL query

Making GraphQL Requests using HTTP Methods

GraphQL Mutation vs Query – When to use a GraphQL Mutation

What is GraphQL? GraphQL introduction

Past posts

Why use GraphQL?

Using nullability in GraphQL

GraphQL vs. REST

Tutorial: GraphQL Input Types and Custom Resolvers

Designing GraphQL Mutations

The Anatomy of a GraphQL Query

GraphQL

Using the GitHub GraphQL API with Apollo Studio Explorer

Designing Your First GraphQL Schema

Demystifying GraphQL Misconceptions | Top Five GraphQL Myths Debunked

Journey of a GraphQL query

Making GraphQL Requests using HTTP Methods

GraphQL Mutation vs Query – When to use a GraphQL Mutation

What is GraphQL? GraphQL introduction

Past posts

Why use GraphQL?

Using nullability in GraphQL

GraphQL vs. REST

Tutorial: GraphQL Input Types and Custom Resolvers

Designing GraphQL Mutations

The Anatomy of a GraphQL Query

Stay in our orbit