Enhance customer experiences with Apollo GraphOS


<p>A healthy graph is never still — new features appear, old ones are pruned, and regretful decisions are repaired (“at last, my schema is perfect” &#8211; said no one ever).</p>



<p>But planning for change requires graph maintainers to tread carefully &#8211; the more you know about how your schema is being used, the more confidently and quickly you can move. With the new Field Insights page in Apollo Studio, safe and rapid innovation of your graph just got a whole lot easier.</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="600" height="450" src="https://wp.apollographql.com/wp-content/uploads/2022/09/image-3.png" alt="My schema is perfect - said no one ever." class="wp-image-15888" srcset="https://wp.apollographql.com/wp-content/uploads/2022/09/image-3.png 600w, https://wp.apollographql.com/wp-content/uploads/2022/09/image-3-300x225.png 300w" sizes="auto, (max-width: 600px) 100vw, 600px" /></figure>



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



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



<p>Fields are the last stop for querying data from the graph. They represent the atoms of information that are exposed to the outside world. They are also functions &#8211; when used in a mutation, they are the entry points that trigger actions in the graph. Every field is literally a “feature” of the graph, and if we want to measure the usage or health of our graph’s features, the field is a great place to start. Maintaining a graph comes with a mindset of continuous curation, and knowing where to focus our improvements is key.</p>



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



<p>Crucially, fields also model the relationships that bind objects together. This is what makes GraphQL uniquely powerful — queries can move freely about the graph, jumping from one entity to the next and fetching as much or as little data as they need along the way. But if one of these links breaks down, entire subtrees can go dark. This is of special concern in a federated context where fields provide the bridge between the business domains in your API.</p>



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



<p>Viewing usage data through the lens of your fields unlocks some essential graph health workflows. With field insights, we are bringing these capabilities into focus for your graph:</p>



<ol class="wp-block-list"><li><strong>Understand usage and adoption patterns.</strong> Client usage breakdowns make it easy to see how client applications and operations are using the field, and field usage over time tells you whether field usage is ramping up or down.</li><li><strong>Identify impact on user-facing apps.</strong> Understand earlier in the schema lifecycle the changes that are likely to impact end-users and other team members based on observed usage.</li><li><strong>Guide change workflows</strong>. Confidently deprecate and remove outdated or unused fields. See the first and last time a field was used, then verify changes with <a href="https://www.apollographql.com/docs/studio/schema-checks">schema checks</a> at release time.</li><li><strong>Assess field-level health.</strong> Per-field error rates and latency histograms help you pinpoint health issues in your graph to target optimization work and validate improvements.</li><li><strong>Understand federation dependencies.</strong> Discover which subgraphs participate in resolving a field as teams work together to build the graph. (Hint: use the <code>@contact</code> directive in your subgraphs to let teams know how to get in touch with one another!)</li></ol>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="584" src="https://wp.apollographql.com/wp-content/uploads/2022/09/image-4-1024x584.png" alt="" class="wp-image-15890" srcset="https://wp.apollographql.com/wp-content/uploads/2022/09/image-4-1024x584.png 1024w, https://wp.apollographql.com/wp-content/uploads/2022/09/image-4-300x171.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/09/image-4-768x438.png 768w, https://wp.apollographql.com/wp-content/uploads/2022/09/image-4-1200x684.png 1200w, https://wp.apollographql.com/wp-content/uploads/2022/09/image-4.png 1371w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>New field-level insights for your graph.</figcaption></figure>



<p>The amazing flexibility of GraphQL has been game-changing for app developers, but it does present an observability challenge. With operations of all shapes and sizes, how can we best understand which parts of the graph are being used, how much, and by whom? What parts of the schema are unhealthy or causing performance bottlenecks for the graph? With the new Field Insights page, you’ll have a powerful new tool to answer these kinds of questions.</p>



<p>Field Insights are available to all organizations, with longer data retention offered on paid Apollo plans. As always, we’d <a href="https://docs.google.com/forms/d/1lC-7aWNe4pnxcAPTB-W4-N8jZoyD_xQXzVByD6HOZpc/edit">love your feedback</a> on how we could further improve your graph workflows.</p>



<p>⚠️ <em>Note that field latency and execution stats require the use of field-level instrumentation in your server or subgraph &#8211; for details on how to configure your server, see </em><a href="https://www.apollographql.com/docs/studio/metrics/field-usage"><em>our documentation.</em></a></p>


Continuously improve your graph with field-level usage and health metrics from Apollo Studio.


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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


Designing Your First GraphQL Schema

Part 2 of 2, Best Practices of Schema Governance with the word "governance" crossed out and replaced with "stewardship"

10 Best Practices for Schema Stewardship (Part 2 of 2)

10 Best Practices for Schema Stewardship (Part 1 of 2)


<p><em>This is a guest post by Marc-Andre Giroux, who is currently working on the ecosystem API team at GitHub. He’s been writing and thinking a lot about GraphQL continuous evolution and schema design. His book, <a rel="noreferrer noopener" href="https://productionreadygraphql.com/book/" target="_blank">Production Ready GraphQL</a>, was released in early March 2020.</em></p>



<p>While GraphQL allows us to continuously evolve our schemas, using deprecations, for example, we should not take the decision of deprecating schema members lightly. In the end, a deprecation still requires work from all your integrators in the best case and is breaking change for anyone that has not made the change in the worst case.</p>



<p>While it’s possible to make these changes in an easier way for everyone with better tooling and documentation like what we’ve&nbsp;<a href="https://developer.github.com/v4/breaking_changes/" target="_blank" rel="noreferrer noopener">built</a>&nbsp;at&nbsp;<a href="https://developer.github.com/v4/changelog/" target="_blank" rel="noreferrer noopener">GitHub</a>, we must keep in mind that using deprecations should be absolute&nbsp;<strong>last resort&nbsp;</strong>if we want a&nbsp;<strong>stable</strong>&nbsp;API in which our integrators can&nbsp;<strong>trust</strong>.</p>



<p>The good thing is that there are ways to build our GraphQL schema in a way that could avoid serious breaking changes in the future. When building our API, we must keep in mind that things will evolve, and to set ourselves up for success when that happens. In this post, we’ll explore a few things that can help when designing our API for the future.</p>



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



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="362" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1024x362.png" alt="" class="wp-image-760" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1024x362.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-300x106.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-768x271.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1536x542.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg-1200x424.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_C57m1JqOzNPHLgL04JYWsg.png 1580w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Take for example this&nbsp;<code>CalendarEvent</code>&nbsp;type. Notice the&nbsp;<code>timeRange</code>&nbsp;field, which represents when the event starts, and ends. At a first glance, this looks alright. We’ve got a list type, which probably matches what we have internally, represented in an array with index&nbsp;<code>0</code>&nbsp;being the start, and index&nbsp;<code>1</code>&nbsp;being the end.</p>



<p>Now what if we wanted to add some more data related to the range? For example if that time range is in the past or future? Well in it’s current state, we’d have to add a field to&nbsp;<code>CalendarEvent</code>. We’d prefix it by&nbsp;<code>timeRange</code>&nbsp;to let our integrators know they’re related. Or worst, we’d end up deprecating&nbsp;<code>timeRange</code>&nbsp;and come up with a different design for the&nbsp;<code>timeRange</code>&nbsp;field.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="408" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1024x408.png" alt="" class="wp-image-761" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1024x408.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-300x120.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-768x306.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1536x612.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w-1200x478.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_qDZOmJzQ__MiBqYiXDcr0w.png 1580w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>This looks slightly off 🤔</figcaption></figure>



<p>The problem here is that we could not add this data in the same&nbsp;<code>timeRange</code>&nbsp;field since we’re stuck with a plain&nbsp;<code>DateTime</code>&nbsp;array. What if we had designed the&nbsp;<code>timeRange</code>&nbsp;field differently to begin with? If we used an object type instead of an array here, we could’ve end up with something like this:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="508" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-1024x508.png" alt="" class="wp-image-762" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-1024x508.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-300x149.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-768x381.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw-1200x595.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_AS8fZJhGG1dav60X096BNw.png 1488w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>This is much better for a few reasons:</p>



<ol class="wp-block-list"><li>We are free to add any additional data we want at no cost to the&nbsp;<code>TimeRange</code>&nbsp;type.</li><li>We have named our fields, instead of using array indexes, which is a lot funner to use for integrators.</li><li>Related data is found within a single type instead of using a field name prefix to do so.</li></ol>



<p>Try to think if the type you’re using for your field or argument is future proof. When in doubt, use a more complex structure like an object type or an input type.</p>



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



<p>When we start building a GraphQL Schema, the whole namespace of names is available to us. When building a new type, it’s tempting to use the simplest thing possible to describe the new entity. For example, take a&nbsp;<code>Comment</code>&nbsp;type which describes a comment on an post someone made on&nbsp;<em>SomeSocialMedia™️</em>.</p>



<p>For a while, this may work perfectly for us. However, we might eventually introduce another kind of&nbsp;<code>Comment</code>&nbsp;, and maybe this comment is actually different. This new comment class for example, might be a feedback form comment for our new app. It’s purpose is completely different, it has different fields, but also common fields.</p>



<p>Now we have to name that new comment something like&nbsp;<code>FeedbackFormComment</code>. We’re stuck with a generic&nbsp;<code>Comment</code>&nbsp;object type representing a post comment. Imagine if we wanted to come up with a&nbsp;<code>Comment</code>&nbsp;interface now that we realize we have a few types with the same behavior. Well our post comment has now stolen our generic name for the interface 😾.</p>



<p>Now we need to go through the hard and long problem of deprecating all fields with type&nbsp;<code>Comment</code>. Creating an interface with a less ideal name, removing the old fields, and finally renaming the interface to&nbsp;<code>Comment</code>. It’s not a fun thing to go through.</p>



<p>Type changes like these take 3 steps to complete:</p>



<ol class="wp-block-list"><li>Deprecate existing fields, and create new fields with a new and temporary name.</li><li>Remove all existing members with the desired name, and deprecate the newly created fields since we will rename them to the desired name.</li><li>Remove the temporary fields, and add them back with the desired name, which is now free to use.</li></ol>



<p>If we initially named our type&nbsp;<code>PostComment</code>, it would have left us some room to clearly define what a&nbsp;<code>Comment</code>&nbsp;was.</p>



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



<p>Some structures are hard to describe using GraphQL’s type system. For example, recursive data structures can be very hard to model with GraphQL and might require us to use a custom scalar to represent correctly.</p>



<p>In most cases though, GraphQL’s type system gives us enough tools to model anything in our schema instead of relying on JSON scalars or any custom scalars.</p>



<p>There’s a few problems with over-using custom scalars:</p>



<ol class="wp-block-list"><li>We lose any introspection ability. It’s hard for our clients to know what the shape of data will be returned from a field returning one of these scalars.</li><li>On the server side, we have now no idea on how this data is used by our integrators. It makes it very hard to make changes to the structure of those custom scalars. We can’t use GraphQL deprecation to do so since we are not using GraphQL fields within that returned payload.</li></ol>



<p>Another similar example is using strings when we could easily represent the field using an&nbsp;<code>enum</code>. For example, with a&nbsp;<code>status</code>&nbsp;field of type String, our clients need to guess the possible values for status. It makes it hard for us to add or remove values because they can’t possibly be handled by our clients. Using an enum allows clients to know when the field changes, or at least lets us use deprecations when needed.</p>



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



<p>This one is a bit less practical but I still believe it’s one of the most important things we need to care about when building any API that will last and will be great to use by our integrators. When designing the shape of your GraphQL schema, try to truly understand what you’re trying to model, and understand your domain the best you can.</p>



<p>With GraphQL having a type system, we see a lot of tools appearing these days that try to generate GraphQL types from databases, ActiveRecord models, or a REST API. While this is tempting to use, and definitely useful at times, by copying our data model or an existing API, we forget to that GraphQL lets us really shape the interface we want to our domain. Try to use that power instead of shaping your API using your data’s shape as inspiration (Avoid&nbsp;<a href="https://medium.com/@__xuorig__/graphql-mutation-design-anemic-mutations-dd107ba70496" target="_blank" rel="noreferrer noopener">Anemic GraphQL</a>).</p>



<p>By doing that, implementation details can change but your API should stay stable(r) as long as we modeled our domain correctly!</p>



<p>Thank for reading ❤️ If you’ve enjoyed this post, you would probably like <a rel="noreferrer noopener" href="https://book.graphqlschemadesign.com/" target="_blank">Production Ready GraphQL</a>, a book that I worked hard on releasing. </p>


GraphQL Schema Design: Building Evolvable Schemas

Three ways to represent your GraphQL schema


<p>As your GraphQL application grows from demo, to proof of concept, to production, the complexity of your schema and resolvers will grow in tandem. To organize your code, you’ll want to split up your schema types and the associated resolvers into multiple files.</p>



<p>We get this question frequently since there are a lot of different approaches to splitting up your schema code, and it might seem that you need a complex setup to get a good result. But it turns out that we can arrange our schema and resolver code in separate files with just a few simple JavaScript concepts.</p>



<p>In this post, we present a straightforward method for modularizing schemas built with&nbsp;<code>graphql-tools</code>&nbsp;that you can tweak to match your tastes and your codebase.</p>



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



<p>If you’re just starting out and have your entire schema defined in one file, it might look much like the below snippet. Here, we’ll call it&nbsp;<code>schema.js</code>:</p>



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

const typeDefs = `
  type Query {
    author(id: Int!): Post
    book(id: Int!): Post
  }  

  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }  

  type Book {
    title: String
    author: Author
  }
`;

makeExecutableSchema({
  typeDefs: typeDefs,
  resolvers: {},
});</code></pre>



<p>Ideally, instead of having everything in one schema definition string, we’d like to put the schema types for&nbsp;<code>Author</code>&nbsp;and&nbsp;<code>Book</code>&nbsp;in files called&nbsp;<code>author.js</code>&nbsp;and&nbsp;<code>book.js</code>.</p>



<p>At the end of the day, the schema definitions we’ve written in the Schema Definition Language (SDL) are just strings. Treating them as such, we have a simple way of importing type definitions across different files: Split up the string into multiple strings that we can combine later. This is what&nbsp;<code>author.js</code>&nbsp;would look like:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// author.js
export const typeDef = `
  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }
`;</code></pre>



<p>Here’s&nbsp;<code>book.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// book.js
export const typeDef = `
  type Book {
    title: String
    author: Author
  }
`;</code></pre>



<p>Finally, we pull it all together in&nbsp;<code>schema.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// schema.js
import { typeDef as Author } from &#039;./author.js&#039;;
import { typeDef as Book } from &#039;./book.js&#039;;

const Query = `
  type Query {
    author(id: Int!): Post
    book(id: Int!): Post
  }
`;

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers: {},
});</code></pre>



<p>We’re not doing anything fancy here: we’re just importing strings that happen to contain some SDL. Note that for convenience you don’t need to combine the strings yourself —&nbsp;<code>makeExecutableSchema</code>&nbsp;can actually accept an array of type definitions directly to facilitate this approach.</p>



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



<p>Now that we have a way to chop up our schema into logical parts, we want to be able to move each resolver with its associated part of the schema as well. In general, we want to keep resolvers for a certain type in the same file as the schema definition for that type.</p>



<p>Expanding on our previous example, here’s our&nbsp;<code>schema.js</code>&nbsp;file with some resolvers added into the picture:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// schema.js
import { typeDef as Author } from &#039;./author.js&#039;;
import { typeDef as Book } from &#039;./book.js&#039;;

const Query = `
  type Query {
    author(id: Int!): Post
    book(id: Int!): Post
  }
`;

const resolvers = {
  Query: {
    author: () =&gt; { ... },
    book: () =&gt; { ... },
  },
  Author: {
    name: () =&gt; { ... },
  },
  Book: {
    title: () =&gt; { ... },
  },
};

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers,
});</code></pre>



<p>Just like we split up the schema definition string, we can split up the&nbsp;<code>resolvers</code>&nbsp;object. We can put a piece of it in&nbsp;<code>author.js</code>, another in&nbsp;<code>book.js</code>, and then import them and use the&nbsp;<code>lodash.merge</code>&nbsp;function to put it all together in&nbsp;<code>schema.js</code>.</p>



<p>Here’s what&nbsp;<code>author.js</code>&nbsp;would look like in that case:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// author.js
export const typeDef = `
  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }
`;

export const resolvers = {
  Author: {
    books: () =&gt; { ... },
  }
};</code></pre>



<p>Here’s&nbsp;<code>book.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// book.js
export const typeDef = `
  type Book {
    title: String
    author: Author
  }
`;

export const resolvers = {
  Book: {
    author: () =&gt; { ... },
  }
};</code></pre>



<p>Then, we apply&nbsp;<code>lodash.merge</code>&nbsp;in&nbsp;<code>schema.js</code>&nbsp;to put everything together:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { merge } from &#039;lodash&#039;;
import { 
  typeDef as Author, 
  resolvers as authorResolvers,
} from &#039;./author.js&#039;;
import { 
  typeDef as Book, 
  resolvers as bookResolvers,
} from &#039;./book.js&#039;;

const Query = `
  type Query {
    author(id: Int!): Author
    book(id: Int!): Book
  }
`;

const resolvers = {
  Query: { 
    ...,
  }
};

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers: merge(resolvers, authorResolvers, bookResolvers),
});</code></pre>



<p>And that gives us the&nbsp;<code>resolvers</code>&nbsp;structure that we started out with!</p>



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



<p>We’re still defining&nbsp;<code>authors</code>&nbsp;and&nbsp;<code>books</code>&nbsp;as top-level fields on&nbsp;<code>Query</code>&nbsp;within&nbsp;<code>schema.js</code>, even though these are logically tied to&nbsp;<code>Author</code>&nbsp;and&nbsp;<code>Book</code>&nbsp;and should live in&nbsp;<code>author.js</code>&nbsp;and&nbsp;<code>book.js</code>.</p>



<p>To accomplish that, we can use type extensions. We can define our existing&nbsp;<code>Query</code>&nbsp;type like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const Query = `
  type Query {
    _empty: String
  }
  
  extend type Query {
    author(id: Int!): Author 
  }
  
  extend type Query {
    book(id: Int!): Book 
  }
`;</code></pre>



<p><em>Note: In the current version of GraphQL, you can’t have an empty type even if you intend to extend it later. So we need to make sure the Query type has at least one field — in this case we can add a fake _empty field. Hopefully in future versions it will be possible to have an empty type to be extended later.</em></p>



<p>Basically, the&nbsp;<code>extend</code>&nbsp;keyword lets us add fields to an already-defined type. We can use this keyword in order to define Query fields relevant to those types in&nbsp;<code>book.js</code>&nbsp;and&nbsp;<code>author.js</code>. We should then also move to defining the Query resolvers for those types in the same place.</p>



<p>Here’s what&nbsp;<code>author.js</code>&nbsp;looks like with this approach:</p>



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

export const typeDef = `
  extend type Query {
    author(id: Int!): Author
  }  
  
  type Author {
    id: Int!
    firstName: String
    lastName: String
    books: [Book]
  }
`;

export const resolvers = {
  Query: {
    author: () =&gt; { ... },
  },
  Author: {
    books: () =&gt; { ... },
  }
};</code></pre>



<p>This is what&nbsp;<code>book.js</code>&nbsp;looks like:</p>



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

export const typeDef = `
  extend type Query {
    book(id: Int!): Book
  }  

  type Book {
    title: String
    author: Author
  }
`;

export const resolvers = {
  Query: {
    book: () =&gt; { ... },
  },
  Book: {
    author: () =&gt; { ... },
  }
};</code></pre>



<p>Just as before, we put it all together in&nbsp;<code>schema.js</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { merge } from &#039;lodash&#039;;
import { 
  typeDef as Author, 
  resolvers as authorResolvers,
} from &#039;./author.js&#039;;
import { 
  typeDef as Book, 
  resolvers as bookResolvers,
} from &#039;./book.js&#039;; 

// If you had Query fields not associated with a
// specific type you could put them here
const Query = `
  type Query {
    _empty: String
  }
`;

const resolvers = {};

makeExecutableSchema({
  typeDefs: [ Query, Author, Book ],
  resolvers: merge(resolvers, authorResolvers, bookResolvers),
});</code></pre>



<p>Now, the schema and resolver definitions are properly co-located with the associated types!</p>



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



<p>We’ve just been through the mechanics of modularizing your server code. Here are a few additional tips that may be helpful in figuring out how to carve up your codebase:</p>



<ol class="wp-block-list"><li>When learning, prototyping or even building a POC, putting your whole schema in a single file is likely fine: There are benefits to be able to go through your whole schema really quickly, or explain it to a coworker.</li><li>You can organize your schema and resolvers by feature: for example, putting the stuff related to the checkout system together might make sense in an ecommerce site.</li><li>Keep your resolvers in the same file as the schema definition for the fields they implement. This will allow you to reason about your code efficiently.</li><li>Wrap your SDL type definitions with a&nbsp;<code>gql</code>&nbsp;tag using&nbsp;<a href="https://github.com/apollographql/graphql-tag" target="_blank" rel="noreferrer noopener">graphql-tag</a>. If you’re using a GraphQL plugin for your editor or formatting your code with Prettier, you’ll be able to get syntax highlighting for SDL within your code editor as long as you prefix it with the&nbsp;<code>gql</code>&nbsp;tag.</li></ol>



<p>Now, go forth and organize your code!</p>


Backend

Continuously improve your graph with field-level usage and health metrics from Apollo Studio.

Generated GraphQL Schemas and Schema Design

Schema-First vs Code-Only GraphQL

Designing Your First GraphQL Schema

10 Best Practices for Schema Stewardship (Part 2 of 2)

10 Best Practices for Schema Stewardship (Part 1 of 2)

GraphQL Schema Design: Building Evolvable Schemas

Past posts

Three ways to represent your GraphQL schema

Modularizing your GraphQL schema code

Backend

Continuously improve your graph with field-level usage and health metrics from Apollo Studio.

Generated GraphQL Schemas and Schema Design

Schema-First vs Code-Only GraphQL

Designing Your First GraphQL Schema

10 Best Practices for Schema Stewardship (Part 2 of 2)

10 Best Practices for Schema Stewardship (Part 1 of 2)

GraphQL Schema Design: Building Evolvable Schemas

Past posts

Three ways to represent your GraphQL schema

Modularizing your GraphQL schema code

Stay in our orbit