
<p>As of today, you can now use our new public API to integrate with the Apollo GraphOS platform.</p>



<p>We built this API to enable those using GraphOS to easily automate operations in their own systems and CI workflows. In fact, this is the same API that the <a href="https://www.apollographql.com/docs/rover/">Rover CLI</a> uses to run schema checks and publish schemas to Apollo Studio.</p>



<p>Under the hood, the GraphOS platform API uses schema <a href="https://www.apollographql.com/blog/announcement/platform/contracts-are-now-generally-available/">contracts</a> to make our private platform API publicly available. By creating a contract, we can filter out the necessary subset of our private platform API schema, all the while keeping the public schema in sync with the source.</p>



<p>See the <a href="https://studio.apollographql.com/public/apollo-platform/home?variant=main">API’s readme</a> to get started, and check out the operation collections in Explorer to see example GraphQL queries and mutations you can use for your own graphs.&nbsp;</p>



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



<p>So, let’s try it out! We’ve embedded the API’s Explorer from Studio below. (Yes, you can <a href="https://www.apollographql.com/docs/studio/explorer/embed-explorer/">embed the Explorer</a> for any of your graphs managed in Studio!)&nbsp;</p>



<p>Here are some examples of what you can do with the GraphOS platform API:</p>



<ul class="wp-block-list"><li>Retrieve a list of your GraphQL supergraphs</li><li>Fetch a graph for a specific environment (such as staging)</li><li>Publish your supergraph’s schema</li><li>Check your supergraph’s schema for errors</li></ul>



<p>Note: Some of these operations, like publishing a new graph, require that you set your own Studio API key. See the <a href="https://studio.apollographql.com/public/apollo-platform/home?variant=main">readme</a> for instructions.&nbsp;<br>Check out our operations collections and try running some queries, read the API’s inline documentation, or see the <a href="https://studio.apollographql.com/public/apollo-platform/schema/reference?variant=main">schema reference</a> to view all the API’s types and fields:</p>



<div style="width: 100%; height: 500px;" id="embedded-explorer"></div>
<script src="https://embeddable-explorer.cdn.apollographql.com/_latest/embeddable-explorer.umd.production.min.js"></script> 
<script>
  new window.EmbeddedExplorer({
    target: '#embedded-explorer',
    graphRef: 'apollo-platform@main',
    persistExplorerState: true,
    initialState: {
      document: ` # Fetches basic details about a single Studio graph
# by its ID.
#
# By default, this fetches details for the
# apollo-platform graph and its main variant, 
# which you're currently querying! You can provide a 
# different graph ID in the Variables panel.
#
# ⚠️ If you provide a non-public graph ID, you
#    need to provide a valid API key in the
#    X-API-KEY header!
query GetGraph($graphId: ID!, $name: String!) {
  graph(id: $graphId) {
    id
    title
    myRole # Null if querying a public graph anonymously
    variant(name: $name) {
      id
      url
    }
  }
}`,
      variables: {
  "graphId": "apollo-platform",
  "name": "main"
},
      headers: {"apollographql-client-name":"explorer","apollographql-client-version":"1.0"},
      displayOptions: {
        showHeadersAndEnvVars: true, 
        docsPanelState: 'closed', 
        theme: 'dark',
      },
    },
  });
</script>



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



<p>In most cases, you’ll want to use the Apollo Rover CLI to manage and publish your GraphQL supergraph schema. As developers iterate on their subgraphs, we recommend regularly running schema checks to ensure that their updated graphs properly compose into a supergraph. If you use continuous integration (CI), we recommend integrating Rover into your pipeline. <a href="https://www.apollographql.com/docs/rover/ci-cd">Here’s how to get started</a>.</p>



<p>If you need to do more complex operations, then you might want to use the GraphOS platform API. For instance, you might want your CI pipeline to create a new Studio variant for each test run, then delete that variant when the run finishes. To accomplish this, you can do the following using the Platform API:</p>



<ul class="wp-block-list"><li>Create a test variant by <a href="https://studio.apollographql.com/public/apollo-platform/home?variant=main#publishing-schemas">Publishing your schema(s) to it</a>.</li><li>Perform any desired tests (such as <a href="https://studio.apollographql.com/public/apollo-platform/home?variant=main#running-schema-checks">schema checks</a>) on the test variant.</li><li>Delete the variant with the corresponding <a href="https://studio.apollographql.com/public/apollo-platform/home?variant=main#destructive-actions">destructive action</a>.</li></ul>



<p>In the near future, we will post about other ways to integrate with the GraphOS platform, such as using the platform API with your governance workflows for your supergraphs. We also look forward to learning how you will use the API!</p>



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



<p>This is just the start for the GraphOS platform API! We are continuing to add new features to both GraphOS and the platform API to make it easier for you to get your schema changes safely to production, to keep your teams up-to-date, and to ensure that clients consuming your graph never experience breaking changes.</p>



<p>To stay up-to-date on what’s coming next with the GraphOS platform API, <a href="https://github.com/apollographql/apollo-studio-community">star and watch the Apollo Studio Community GitHub project</a>. We will be sharing more about the GraphOS platform API roadmap there and here in the Apollo blog.</p>



<p>You can help us by letting us know what you’d like added to the API by creating a GitHub issue or by giving us feedback in the <a href="https://community.apollographql.com/">Apollo Community</a>.&nbsp;</p>



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



<p>Still getting started with a single GraphQL server or new to GraphQL? No problem. We&#8217;ve made it easier than ever to leverage all of the analytics and automation of supergraphs in Studio. <a href="https://apollographql.com/tutorials?ref=www">Create your first graph</a> and make your first graph query in under an hour.</p>


Integrate with GraphOS using the new Platform API


<p>Let’s consider the core promise of GraphQL:</p>



<p><strong>Get exactly what you need and nothing more with a single query.</strong></p>



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



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



<p>One graph → one endpoint → client apps have access to everything, including cardholder information and other sensitive data. Right?</p>



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



<p><strong>That’s it.</strong></p>



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



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



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


How Priceline.com manages PCI compliance with GraphQL


<p>GraphQL is a type-safe language for APIs. A common misunderstanding is that<a href="https://www.apollographql.com/docs/resources/faq/#what-is-graphql"> GraphQL is another complete query language</a>, like SQL, which allows you to search, filter, and select all the objects in a database. Instead, GraphQL should be thought of as a way to specify the types of data available and the specific operations users can perform over an API. It allows backend services and the clients consuming them to have a shared understanding of an API, and gives clients more control in selecting what parts of the data they would like to get back for a given operation. All of this is accomplished with the<a href="https://www.apollographql.com/docs/tutorial/schema"> GraphQL schema</a>.</p>



<p>A GraphQL schema is a machine and human-readable document that declares what operations are available and what types those operations return. The schema is the contract between a GraphQL server and its clients, which means that, inevitably, there are various opinions on what is good schema design. At Apollo, we have the unique opportunity to work with various GraphQL users as they build their schemas and we have documented much of what we have seen in<a href="https://principledgraphql.com/"> Principled GraphQL</a> and our<a href="https://www.apollographql.com/docs/federation/enterprise-guide/introduction/"> Enterprise Guide for Federation</a>. However, there is a common question that comes up when we start talking about schema design: “Should I manually craft my schema or generate it from my existing data types?”</p>



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



<p>Before we dive into the question, I need to clarify some common terms used in the GraphQL ecosystem.</p>



<p><em><br></em>There are two ways you can write your GraphQL schema. They are with a <a href="https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql/" target="_blank" rel="noreferrer noopener">schema-first pattern or using a code-only pattern</a>. These methods differ in how the schemas are defined, but both allow API developers to declare their own types that are separate from the underlying data sources. Each of these patterns has its trade-offs but is outside the scope of this post.</p>



<p>The term generated schema is separate from schema-first and code-only. This refers to tools that can take some external data types or non-GraphQL schema and generate a GraphQL schema and/or the resolvers with exactly the same types. These tools allow you to take existing data sources, like REST APIs or SQL databases, and quickly add a GraphQL API on top of them with the same types. Clients can then start taking advantage of the benefits of GraphQL, like being able to customize the response selection or merge data sources together, with minimal upfront cost.</p>



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



<p>One of the core tenants of Apollo’s Enterprise Guide for schema design is having a<a href="https://www.apollographql.com/docs/federation/enterprise-guide/federated-schema-design/#best-practice-2-design-schemas-in-a-demand-oriented-abstract-way"> Demand (Client) Oriented Schema</a>. This means that the schema should act as an abstraction layer that provides flexibility to consumers while hiding service implementation details. A client-oriented schema can be built with a schema-first or code-only approach. In both patterns, we have the opportunity to communicate beforehand with all the users of our API, understand their needs, and design and build an API schema that can serve them all, without requiring every client to write additional transformation logic on top of our data. This is also called product-driven schema development, because the end goal is to be able to ship new features to our product with a minimal amount of effort, for all teams involved.</p>



<p>You will notice though, that generated schemas are not included. This is because generated schemas do not allow us to make changes to the types. They expose types that exist in other data sources in a single schema and possibly connect them in some way, but the data that our clients get back is still the same if they had called the underlying data sources themselves. Any transformations or additional merging of data must be done by all the clients, which means duplication of code shipped to your client apps.</p>



<p>If these tools are counter to one of the core principles of GraphQL schema design, you may be asking yourself: When should I use a generated schema?</p>



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



<p>The primary benefit of generating a GraphQL API is the upfront cost to get started. If you have clients today that have to talk to 5 different databases, GraphQL can be a great tool to merge all those data sources into one schema and give some flexibility to your clients to select specific parts of the return data. If you have a small team and you don’t have time to build a new GraphQL layer or learn about how to deploy a new server to your infrastructure, the ability to get something up in running a matter of hours, or even minutes, can be incredibly powerful.</p>



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



<p>Apollo has a recurring meeting with some of our customers and their<a href="https://www.apollographql.com/graph-champions/"> Graph Champions</a>, and we posed this question to them to hopefully get more insights from real developers in the enterprise and deploying GraphQL at scale: “Have you used or created a Generated GraphQL API and would you recommend other companies to use one?”. Their feedback echoed many of the points we have made already but brought up some interesting ideas.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>(A generated schema tool) infers all the fields from the database and then it exposes GraphQL in a really incredibly powerful query language where you can get stuff from the DB, and I know a lot of projects that have gotten up really quickly with that insanely fast.</p><p>The way I like to phrase this when I am talking to teams that are wanting to bring this on is, instead of dictating what they should be doing, I explain to them what clean architecture should look like and then frame it in the context of exactly what you said, but say ‘What are your expectations with being able to change this? If you remove a field from the database, what does that do? Or if you need to pull something out into a completely different service because it has independent scaling needs, what does that look like?’. If they are ok with not changing anything then maybe this is ok.</p><p>Say you are exposing <code>first_name</code> from the DB directly, what happens when you need to migrate to expose that with<a href="https://www.elastic.co/"> Elasticsearch</a>?</p><cite>Staff Software Engineer &#8211; Medical Tech Company</cite></blockquote>



<p>This brings up the idea of what a migration strategy might look like in a generated schema when you want to move your database from a SQL format to a document-based or graph-based DB. Since the API is mapped 1-to-1 on the types from your tables, the clients are making requests against field names that map to rows and columns. If there doesn’t exist the same pattern in your new storage format, it could be difficult to have a completely-backward compatible schema, which means your clients would have to migrate to a new API or different types when you want to change your database.</p>



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



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>We started off using a v1 of (a generating tool). You could define the key and table you connect to, and you would think in types, but then (the tool) would say ‘You can not do this change’. I know the database and I know in SQL it could work, but (the tool) would say: ‘This is going to break your relationship’. So you would go and start changing the first layer of schema, and then update the relationships. So you are changing the schema which you shouldn’t be doing (often) in GraphQL. You won’t see that in the beginning though, the more schema you add and the more database tables you keep generating, is when you start seeing issues.</p><cite>Engineer Lead &#8211; Food &amp; Beverage Retail Company</cite></blockquote>



<p>The team at this company ended up rewriting the GraphQL layer because their clients were constantly having to update their queries, and having to coordinate changes with the backend team. The generating tools helped them get going quickly, but the saved time upfront was not proportional to the added time they had to spend doing schema updates, client changes, and another code rewrite when their graph started to scale. This is not unique to one company though. When teams start adopting GraphQL, regardless of how it is built, it naturally becomes a new central place for cross-team collaboration. For those that spend the extra time in the beginning thinking about how their graph will scale in the future when more clients are using it and more teams are publishing schema changes, it leads to a longer supported and healthier platform.</p>



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



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>This problem is not unique to the graph&#8230;For those of us that have been around a while, I’m sure we all remember back in the day when Microsoft was saying: ‘Just drag your database table onto your Visual Basic form and you’re done!’&#8230;There are tons of common historical questions. I would actually ask a fellow team: ‘Would you generate your REST endpoint directly from the database?’. If they say no, then the next question is why do we want to generate the GraphQL schema?</p><cite>Principal Software Engineer &#8211; Business Expense Management Company</cite></blockquote>



<p>For teams thinking of GraphQL as a query language first, it can be seen as the best tool to solve your data merging needs. However, they are missing the concept that GraphQL is designed to be an API tool, not a data tool. In theory, we could build a similar REST API that merges multiple database calls and caches the results for clients to quickly query later. The reason you would build this is to solve a client problem though, not a database problem. Our databases should remain separate so they can scale independently and solve the storage problems they are designed for. We build abstractions on top of them, either in REST or GraphQL, to hide the details from clients who don’t need to be concerned about them.</p>



<p>This is why historical trends in tech have moved us towards more and more micro-services, but this has now reached a scale for our fellow clients and product developers that has become unmanageable. Having to juggle all the services needed to power a great web or mobile app experience and following updates and breaking changes, is too much for one team. This is where GraphQL has grown the most since its release, because having the ability to see all the services and their capabilities in one schema, and also inform the service owners of what operations clients are performing, gives the power back to client teams.</p>



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



<p>With any problem in tech, there are going to be tradeoffs for any solution you decide to go with. GraphQL has been around for a while, but it is still an emerging ecosystem, so we are just now starting to hear more from developers and teams who have been using the tech for multiple years and some of the decisions they made.</p>



<p>If you are lucky to have the opportunity to create a new GraphQL API, conduct some market research and talk with the end users of your product: your client teams. Ask them how they use the existing products today and what frustrations they have. Ask how you might be able to help reduce those frustrations and remove any work needed from them. For every hour of effort you put in to help your clients, know that you are multiplying your efforts across all the clients you support. With a client-first GraphQL schema in mind, you can then choose the best tool that will help you achieve this goal and keep it running for years to come.</p>


Generated GraphQL Schemas and Schema Design


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



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



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



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



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



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



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



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



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



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



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



<p>There are a few misconceptions that we often hear from the GraphQL community that we would like to address.</p>



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



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



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



<h4 class="wp-block-heading"><a href="#rumor-you-cant-see-the-sdl-with-code-only" aria-hidden="true" class="aal_anchor" id="rumor-you-cant-see-the-sdl-with-code-only"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><em>“<em>Rumor</em></em>: <em>You can’t see the SDL with code-only”</em></h4>



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



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



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



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



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



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



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



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



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



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



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

  extend type Product {
    reviews: [Review]
  }

  # ...other types
`;

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

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

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

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


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



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



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


Schema-First vs Code-Only GraphQL


<p>Apollo Studio Explorer is the most powerful web IDE for creating, running, and managing GraphQL operations. Since launching it over a year ago, we’ve added many new features to Explorer to help you navigate your schema and build queries more intelligently than ever before. To help you get the maximum value out of Explorer, we polled a number of developers from the GraphQL community and compiled a list of the top 5 most useful features you may have missed.</p>



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



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



<p>Did you know that the operations editor can manage multiple operations individually? As you work, the editor shifts focus to whichever operation you click into and updates the run button accordingly. Each operation also has its own context menu (&#8220;<strong>&#8230;</strong>&#8220;) offering various tools specifically for that operation. This makes it easier than ever to manage and test all of your operations independently in a single tab!</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1414" height="768" src="https://wp.apollographql.com/wp-content/uploads/2021/08/multiple-operations.gif" alt="" class="wp-image-8345"/></figure>



<h2 class="wp-block-heading"><a href="#2-table-layout-for-response-data" aria-hidden="true" class="aal_anchor" id="2-table-layout-for-response-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>2. Table layout for response data</h2>



<p>You can view an operation&#8217;s response as JSON or as a table. Table layout is especially useful when your response includes an array, or when you want to share a query&#8217;s results with someone who isn&#8217;t familiar with JSON. When looking at arrays of data in table mode, you can click the header of any column of data to sort your array by that column&#8217;s values.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1433" height="743" src="https://wp.apollographql.com/wp-content/uploads/2021/08/tablemode.gif" alt="" class="wp-image-8347"/></figure>



<h2 class="wp-block-heading"><a href="#3-editor-hints" aria-hidden="true" class="aal_anchor" id="3-editor-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>3. Editor hints</h2>



<p>Under Explorer settings, you can toggle on/off Editor hints to view metadata for each of your operation’s fields, right aligned in the editor. You can toggle any of the following three hints to be displayed:</p>



<ul class="wp-block-list"><li><strong>Response hints:</strong> When toggled on while building your query, the Explorer runs partial queries under the hood and shows their results in-line. This is helpful when you want to get a sense of the data you&#8217;ll get back in your full operation response. It can also help you retrieve a quick answer to a query without needing to click the Run button.</li><li><strong>Subgraph source:</strong> For a federated graph, you can see which subgraph each field in the operation is sourced from.</li><li><strong>Field latency approximations:</strong> The Explorer shows you the 95th-percentile (default) response times for the fields in your query to help you get a sense of how &#8220;expensive&#8221; your query is and what the bottlenecks in response time will be. You can change which percentile you want to see hints from at any time in the Explorer settings.</li></ul>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1003" height="656" src="https://wp.apollographql.com/wp-content/uploads/2021/08/editorhints.gif" alt="" class="wp-image-8349"/></figure>



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



<p>One of our favorite features! This enables you to share with each other the link to the exact operation. Click on the context menu (“…”) at the top of the operation to copy the link that can be used for sharing. Paste the link on a web browser and voila! Explorer with the exact operation is ready to be executed.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="1411" height="841" src="https://wp.apollographql.com/wp-content/uploads/2021/08/copy-link-to-operation.gif" alt="" class="wp-image-8351"/></figure>



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



<p>While editing your operations, you can toggle between inline or extracted notation for variables. This is useful when you want to switch notations to copy and paste something, or when you&#8217;re drafting a query in the editor and want to move it to your code.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="487" height="553" src="https://wp.apollographql.com/wp-content/uploads/2021/08/inline-extract-var.gif" alt="" class="wp-image-8359"/></figure>



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



<p>We can’t wait to see what you’ll build with all of the amazing features that Explorer has to offer! If you’re already an Apollo user, you can access all of these features right now by opening Explorer in <a href="https://studio.apollographql.com/login">Apollo Studio</a>. Or, if you’re new to Apollo and not quite ready to create a Studio account, you can start using much of what Explorer has to offer in <a href="https://studio.apollographql.com/sandbox/explorer">Apollo Sandbox</a>.</p>


The 5 most useful features of Apollo Studio Explorer that you didn’t know existed


<p>Last year, when we launched <a href="https://www.apollographql.com/blog/introducing-the-apollo-explorer/">Apollo Explorer </a>and our schema reference and changelog, we wanted to help you put the power of your graph into the hands of as many people as possible. Starting today, we&#8217;re making it even easier. You can invite everyone in your organization to explore your graph in Apollo Studio using the new Consumer user role. Consumers will have access only to your graph’s Explorer, the schema changelog, and schema reference documentation. Graph champions now have a way to safely bring the graph to every single person in your company, putting the power of your graph in the hands of everyone who would benefit from it.</p>



<p>Even better, you can invite an unlimited number of your team members with a Consumer role in all plan tiers, including our Free and Team plans. Previously, Free and Teams plans only offered admin-level access to your graph, which limited the number of people who could have visibility and access to your graph.</p>



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



<p>With the Consumer role, you can provide visibility and discoverability while preventing people from making unwanted changes. Consumers won’t be able to change any settings, see any operational data or metrics, or make any changes to your schema. These restrictions make it suitable to give out safely to anyone casually using your graph or getting started building applications against your graph. All Consumer users will have instant access to:</p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/docs/studio/explorer/">Apollo Studio Explorer</a>, a feature-packed IDE for formulating and executing sample queries. Users can search for fields and find direct paths that can be run as queries, as well as output data in tables along with lots of other conveniences.</li>
</ul>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/docs/studio/explorer/#the-documentation-tab">Schema reference</a> for automated documentation of your graph’s types and operations. By registering your schema in Apollo Studio you get instant reference material for all of your users.</li>



<li><a href="https://www.apollographql.com/docs/studio/org/graphs/#tracking-schema-changes">Changelog</a> for an automated view of changes between each new schema published in the registry. Make it easy to see the evolution of your graph over time.</li>
</ul>



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



<p>There are two ways you can <a href="https://www.apollographql.com/docs/studio/org/members/#inviting-members">invite</a> people to be Consumers:</p>



<ol class="wp-block-list">
<li>Directly invite members, pre-assigning them the Consumer Role. This can be done from the “Members” tab of your organization’s settings page inside Apollo Studio.<br><img loading="lazy" decoding="async" src="https://lh5.googleusercontent.com/I20p3C0AWQUDNNSjvGi3iqfPCP_H2J_Dh9sBb-yXDdnk5nXAbPSHbjJXzAT7hWV7I3K__ZTq_T4yUYu5Kx0BygMKGEzzqfgJM5GdBL9PH-R1IOcm_JC6LNRVhaXRmkBbpNS9-1TK" width="442" height="259"></li>
</ol>



<ol class="wp-block-list" start="2">
<li>Create a shareable invite link, assigning the default role as Consumer. This can be done from the “Settings” tab of your organization’s settings page inside Apollo Studio.<br><img loading="lazy" decoding="async" src="https://lh3.googleusercontent.com/wiG_NNRB-N8nnMpyLo_21s4ib0HlVRixiYY3SvdWQyGeXVkAUXJ-FR2iYPyAqf1OcBWuW1B95xklXOKlYTkP4mJN6yb90djSyyyo9EdkmjL9D9Gg5a3Nri1UfeZHPWNUW2QupdWO" width="624" height="96"></li>
</ol>



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



<p><a href="httpw://www.apollographql.com/pricing">Apollo Studio Enterprise</a> has unlimited access to the Consumer role as well as Enterprise-only roles of Observer, Contributor, and Graph Admin, along with graph-level roles and protected variants that restrict who can make changes to production or other sensitive environments. To learn more about the Enterprise-only user permissions features visit our <a href="https://www.apollographql.com/docs/studio/org/members/">docs</a>.</p>



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



<p>Come visit our discussion <a href="https://github.com/apollographql/apollo-studio-community/discussions/68">thread</a> about the new Consumer role to let us know what you think.</p>



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



<p>If you aren’t yet using Apollo Studio, you can sign up today for <a href="https://studio.apollographql.com/signup?referrer=blog">free</a>.</p>


Sharing your graph just got a whole lot easier – Announcing unlimited Consumer seats


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>tldr; you can now apply the <a href="https://www.apollographql.com/blog/user-roles-are-now-available-in-apollo-studio/">user roles that we released last fall</a> at a much more granular level.</p></blockquote>



<p>Happy New Year, everyone! Today, we are excited to share a significant expansion of the roles and permissions controls available in Studio. With these updates, you can confidently on-board more teams to your graph by ensuring that everyone has just the level of access they need. Building off <a href="https://www.apollographql.com/blog/user-roles-are-now-available-in-apollo-studio/">the five user roles we introduced last fall</a>:</p>



<ul class="wp-block-list"><li>We have added a sixth role option, <strong>Graph Admin</strong>, that you can assign to users in your organization. Graph Admins will be able to act as full administrators for every graph in your organization but can’t manage your organization’s users, billing, or settings.</li><li>Users can now be assigned <strong>graph-level roles</strong>, which can override their role in the organization for any individual graph.</li><li>You can now mark graphs in your organization <strong>hidden</strong> from the rest of your org’s members by default.</li><li><strong>The API keys you create for your graphs can be assigned roles</strong>, letting you differentiate between read-only keys and admin keys.</li><li><strong>Variants in your graph can now be marked as protected</strong>, limiting mutations to only users or keys with admin-level access.</li></ul>



<p>We hope that these new access controls and protections will cover your needs and eagerly welcome you to share your feedback with us in our <a href="https://github.com/apollographql/apollo-studio-community">Studio community repository</a>. Today’s release is a major step forward in your ability to manage your Studio account as your organization’s graph evolves.<br></p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>These features are part of the Studio Enterprise plan. Please <a href="https://www.apollographql.com/contact-sales/">reach out to us</a> if you are interested in this features and would like to talk to us.</p></blockquote>



<p>Thanks for being a member of our community and coming on this journey with us. Stay safe and healthy, and as always, happy querying!</p>


Graph Roles and Protected Variants Now in Apollo Studio

Graph Roles and Protected Variants Are Now Available in Studio


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>tl;dr Apollo Studio Enterprise announces support for Schema Change Webhooks</p></blockquote>



<p>As GraphQL developers, all of our data is communicated through the GraphQL schema. With the release of schema change Slack notifications in 2020, we made it easier than ever to keep everyone working around your graph up-to-date with schema changes through Slack. Expanding on the functionality to connect your graph’s schema to your workspace, we are excited to announce the addition of <strong>schema change webhooks</strong> to Apollo Studio Enterprise.<br><br>With webhooks, you and your team can build whatever automation is relevant to your workflow, whether that be automating pull requests to client &amp; server codebases, running linting tests, generating email notifications, or creating a personalized change-log. The possibilities are yours to enumerate.<br><br>Setting up schema change webhooks will require:</p>



<ul class="wp-block-list"><li>An Apollo Enterprise subscription</li><li>Configuration in Apollo Studio</li><li>An exposed endpoint to handle the webhook payload</li></ul>



<p>Every time your graph variant’s published schema changes, your configured webhook listener will receive a JSON payload like so:</p>



<pre class="wp-block-preformatted">{<br>  "eventType": "SCHEMA_PUBLISH",<br>  "eventID": "6190b556-457e-4669-b933-8b66aa9b8764",<br>  "changes": [<br>    {<br>      "description": "field `Amazon.referrer`: type `String!` changed to `String`"<br>    }<br>  ],<br>  "graphID": "acephei",<br>  "schemaURL": "https://graphql.api.apollographql.com/schema-link?token=6fb35434a55b966f81c0e07a8f93327029d",<br>  "schemaURLExpiresAt": "2021-01-26T20:05:28.856Z",<br>  "timestamp": "2021-01-25T20:05:28.081Z",<br>  "variantID": "acephei@prod"<br>}</pre>



<p>Configuring a new webhook notification is a few clicks in Apollo Studio. Navigate to the notifications tab in your graph’s Settings page and click <code>Add Notification</code> to get started. For a walk-through, take a look at the dedicated <a href="https://www.apollographql.com/docs/studio/notification-setup/">Studio Notifications docs</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="433" src="https://wp.apollographql.com/wp-content/uploads/2021/01/image-1024x433.png" alt="Screen Shot 2021-01-25 at 3.25.32 PM.png" class="wp-image-6602" srcset="https://wp.apollographql.com/wp-content/uploads/2021/01/image-1024x433.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/01/image-300x127.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/01/image-768x325.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/01/image-1536x650.png 1536w, https://wp.apollographql.com/wp-content/uploads/2021/01/image-2048x866.png 2048w, https://wp.apollographql.com/wp-content/uploads/2021/01/image-1200x507.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/01/image-1980x837.png 1980w" sizes="(max-width: 1024px) 100vw, 1024px" /></figure>



<p>To handle a webhook notification, you’ll expose an endpoint that can consume the JSON payload. We have an example Node.JS server for you to run to handle this event here: <a href="https://github.com/jsegaran/apollo-schema-change-webhook">https://github.com/jsegaran/apollo-schema-change-webhook</a>. Alternatively, it’s simple to get up and running with a custom Zapier integration or whatever your favorite workflow automation tool may be.<br><br>To learn more about schema change webhooks and the other functionality that comes with Apollo Enterprise, <a href="https://www.apollographql.com/contact-sales/">reach out to Apollo</a>!</p>


Apollo Enterprise: Schema Change Webhooks


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



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



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



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



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



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



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



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



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



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



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

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

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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



<p><code>./gradlew downloadApolloSchema --key $API_KEY --graph $GRAPH --variant current&nbsp;</code><br><code>--schema app/src/main/graphql/com/example/schema.sdl</code></p>



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



<p>The initial SDL support was <a href="https://github.com/apollographql/apollo-android/commit/8fccd52b01b7f8e9a7d9dffca0438cb8c97da141">committed</a> a couple of months ago and we’re still working on improving it. <code>convertApolloSchema</code>, for example, is a very recent addition.</p>



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



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


SDL Support in Apollo Android


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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

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



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



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



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



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



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



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



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



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



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

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

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

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

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



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



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



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



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



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



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



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


Tooling

Integrate with GraphOS using the new Platform API

How Priceline.com manages PCI compliance with GraphQL

Generated GraphQL Schemas and Schema Design

Schema-First vs Code-Only GraphQL

The 5 most useful features of Apollo Studio Explorer that you didn’t know existed

Sharing your graph just got a whole lot easier – Announcing unlimited Consumer seats

Graph Roles and Protected Variants Are Now Available in Studio

Past posts

Apollo Enterprise: Schema Change Webhooks

SDL Support in Apollo Android

4 Simple Ways to Call a GraphQL API

Tooling

Integrate with GraphOS using the new Platform API

How Priceline.com manages PCI compliance with GraphQL

Generated GraphQL Schemas and Schema Design

Schema-First vs Code-Only GraphQL

The 5 most useful features of Apollo Studio Explorer that you didn’t know existed

Sharing your graph just got a whole lot easier – Announcing unlimited Consumer seats

Graph Roles and Protected Variants Are Now Available in Studio

Past posts

Apollo Enterprise: Schema Change Webhooks

SDL Support in Apollo Android

4 Simple Ways to Call a GraphQL API

Stay in our orbit