GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

graphql

GraphQL brings joy to using APIs. Even though it's based on a type system, GraphQL in many ways is more flexible than REST.

But the flexibility that makes GraphQL a joy to work with can have its downsides if you aren't careful.

Schema design is an area where one small oversight at the beginning can get you stuck having to deal with weird naming, bloated duplicates, and other annoying workarounds.

It doesn't have to be like this!

Nik Graf has extensive experience designing GraphQL schemas, for a variety of business applications.

In this course, Nik has prepared several examples following different design patterns. Through exploration and comparison, you'll come away with actionable knowledge for designing and extending schemas.

Follow Nik, and avoid making Schema mistakes that will come back to bite you later.

Maxime Bourgeois

Taylor Bell: Hey, Nik, thanks for joining me today.Nik Graf: Hey, happy to be here.Taylor Bell: Yeah, so I wanted to talk to you a bit about your new course about designing graph QL schemas. So why is it important to learn a good way to design a schema?Nik Graf: Well, I can tell you from my past experiences, I made some really big mistakes with some clients, customers, and my own stuff that I shipped and simply because you want to build a schema that stands the test of time. So basically, when you work on it, you don't want to build yourself into a corner where it's hard to get out because you made a decision, and you didn't think it through and then suddenly there's a requirement that comes in, you're like, "Oh, no, this is really bad for what we currently have. I wish we did that in the past."Nik Graf: And there's a couple of patterns and lessons learned that are basically in every domain. They work for every domain, you can apply them and it will simply save you from that hassle and yeah, I've been there and I felt the need like this is... I've seen it so many times, people hire me for React development or helping them move GraphQL and then I see eight, well what you have is exactly, it's problematic. It will hurt you in a couple months or years and yeah, it's a pattern. You know when you see the same problem three times, it's worth it to make the course.Taylor Bell: I think I like that kind of rule of thumb. So, when somebody goes to take your course, what's the journey that you take them on throughout this course?Nik Graf: We start very simple with just basic naming conventions and then it's a little bit of mix and match. We'd be talking about what happens if you're in a situation where things went wrong and how you can get out of it. It requires multiple deploys and some time, time is really the key to do migrations without affecting end users. But the first part is very focused on queries and namings and then connections especially. So how to do pagination, how to do a cursor-based pagination, why cursor's important and then we'd go more into mutations and these are especially hard I think and to be honest, like yeah, there's even more, but I couldn't fit it all in. But yeah, I think this covers a lot of what's really, really important and yeah, I track it all the time. For me, it was read now with 99 hours of work only for the course, getting more the materials, the workshop and so on and it's all squeezed into 56 minutes or so, something like that.Taylor Bell: That's pretty amazing that it can compress that far and still be, still retain all of the value and so it's interesting, something you said about there being more that you wanted to include. What are those next steps that someone should take after they work through this course?Nik Graf: So I think what I haven't touched too much on is how to design as a team a schema. So what, for example, what I do usually when I come into a consulting kick and we talk about new part, a new feature, designing a new part of the schema, often it was... If you look at the... It's very natural that one person creates the schema, doesn't talk to anybody, this is the new schema, now use it and you're done. But the thing is it's in, GraphQL is the intersection point. It's a contract between the backend and one or multiple clients and it's such an opportunity when you design it because when you get at the point where you design it, when you get simply everyone into the room and you just talk about what are the actually needs and do you base it on the use cases, on the screenshots, on the wire frames and so on.Nik Graf: You can really, you can have a great contract that's better for everyone and this is what I usually try to do with everyone is like, "Okay everyone should have a base knowledge about GraphQL," otherwise it doesn't work really well, but then take the time, get together in the room, maybe someone can come with the proposal, but then just look for the use cases and every client and everyone from backend can have their opinion and then you can find the best trade offs and make the best decisions hopefully and yeah, it really is... Designing together, especially when so many people are affected, this helps them and then just mark it out. Everybody can use it already while the backend is pulling out the rest and the clients already can consume it if it's marked service and yeah, maybe I can talk more about this in the future.Taylor Bell: Cool. Well thanks so much for joining me today and congrats on putting in all of this time and then making a wonderful final product.Nik Graf: Thank you. Thank you much.

In this short clip Nik shares why is story how this course came to be.

Course Intro for Designing GraphQL Schemas 

When iterating on new GraphQL schema, it is great to have a server implementation allowing you to only provide type definitions and the server returning mocked results. This enables you to quickly iterate on ideas and verify them with example queries.

Apollo Server offers this by enabling the mocked mode. In this lesson create a new server with mocking enabled, customize mocks and walk through how to combine mocks with resolvers.

This setup then will be the basis for our schema design explorations. Let me add that while Apollo Server works well for this case, any other GraphQL server might do as well.


Setup an Apollo GraphQL Server with automatic Mocking 

When it comes to designing GraphQL schemas it's important to first understand what good design means.

For once it's definitely to have queries, mutations and types **driven by the business domain** in order to let developers build the desired use-cases with ease. Nevertheless a well designed schema also allows you **extend or change it based on new requirements** without making breaking changes.

In this lesson we will walk through a simple process on how to kick off a schema design process based on wireframes or UI designs. In combination with a set of solid conventions this will help you to get started, but still be able to iteratively improve your schema.


Kicking off a GraphQL Schema Design Process

While it's very appealing to pick a short and crisp name for a field, not naming the things exactly what they are can cause issues and confusion in the long run.

In this lesson we walk through one example in detail and see what issues a wrong naming decision can cause. After that we walk through a couple more example to get a better feeling of the recommended convention.

Naming Conventions for Query Fields in GraphQL

In GraphQL every field is nullable by default. While not ideal for the developer experience when consuming a GraphQL Schema with a client, this was a conscious decision by the creators of GraphQL. 

In this lesson we explore the background for this decision which will cover the following areas:

- Error handling
- Authorization
- Deprecations during Schema Migrations


When and Why to use Nullable vs Non-nullable Fields in GraphQL

While it's certainly possible to version a GraphQL Schema, it's common practice to not do so.

That's fine when just adding new queries or fields, but now and then we want to change a type or remove a field. Leveraging multiple deploys and deprecations we can make breaking changes in a GraphQL schema without affecting a single user.

In this lesson we use one field renaming example to walk through such a multi-step process.

Evolving a GraphQL Schema incl. Breaking Changes without affecting a Single User

Naming variations can easily be solved by postfixing the name with the variation. This though can quickly lead to a bloated schema, which we want to avoid.

On the contrary by using arguments our schema becomes less flexible.

In such cases GraphQL Aliases become a vital element to enable developers to do the same things as with multiple fields, but without any of the downsides. 

Naming Conventions for Fields with GraphQL Aliases in Mind

Being able to resolve related entities in one query is one of the most beneficial features of GraphQL.

While the simples solution often is the best, this doesn't hold up for GraphQL connections. The ideal solution is based on the [Relay Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm).

In this lesson we start based on a simple solution and apply one feature request after another. Eventually we end up with the Connection Specification. 

Paginate Entries using the Connection Specification

A Connection can be extended in multiple ways:

- Fields representing meta information on a entity relationship can be added
- PageInfo itself can be enhanced
- Arguments for filtering or ordering can be applied

In this lesson we walk through all of them to demonstrate the flexibility of the Connection Specification.

Extending GraphQL Connections with additional Fields and Arguments

When naming queries there are almost now rules or recommendations. Nevertheless it's recommended to at least have some conventions in order to reduce cognitive overhead for developers.

In this lesson we explore some the the common best practices.

Naming top-level Query Fields in GraphQL

Relay comes with a specification and a set of well define conventions for GraphQL Mutations. By following the conventions, we not only design Mutations in a way that they can be extended with easy, but also reduce a lot of cognitive overhead.

We can summarise the conventions into 5 rules:

1. Mutations are named as verbs `createProduct`, `introduceShip`, `deleteCollection`.
2. There must be a single argument input
3. The input type name is the capitalised mutation name with a `Input` postfix e.g. `CreateProductInput`, `IntroduceShipInput`.
4. The returned value is a new custom type that can contain various fields.
5. The return type is name is the capitalized mutation name with a `Payload` postfix e.g. `CreateProductPayload`, `IntroduceShipPayload`.


Mutation Input and Payload Structure in GraphQL

In this lesson we design the mutations for a webshop checkout flow in two variations. First based on the data model, then based on the domain model.

Once we have both available we can compare them and explore the pros and cons.

Design GraphQL Mutations by focusing on the Domain rather than the Data Model 

In theory it's quite easy to dynamically generate queries at runtime based on a parameter, but not a lot of GraphQL clients handle it well. It's not so much about the clients, but all the tooling around it like generators, editor integrations and the opportunity to leverage persistent queries.

Using plural instead of singular arguments will allow your clients to use static queries for situations where they usually would need dynamic ones.

Optimising GraphQL Mutations for Static Usage

A common requirement for connections is to add and remove items. We could go with two separate mutations: add & remove versus a single update mutation. In almost all situations it's better to have two separate mutations and in this lesson we explore why.

GraphQL Mutations to update Connections

While being specific is great when designing GraphQL Mutations, in some cases this can lead to a large number of Mutations. Especially when the use-case is to update one entity, it raises the question if can or should do just one update mutation.

It's certainly possible, but requires some tradeoffs. Most commonly we have to make non-nullable fields nullable. In this lesson we use an `updateProduct` example to elaborate why this tradeoff is needed.

Tradeoffs when designing GraphQL Mutations to update multiple Properties on one Entity

Feedback & Questions are very welcome at [https://twitter.com/nikgraf](https://twitter.com/nikgraf)

Thanks to everyone involved helping me to create this course, but especially to:
- Mikhail Novikov [https://twitter.com/freiksenet](https://twitter.com/freiksenet)
- Sean Grove [https://twitter.com/sgrove](https://twitter.com/sgrove)
- Marc-André Giroux [https://twitter.com/__xuorig__](https://twitter.com/__xuorig__)

Designing GraphQL Schemas

Nik Graf

What you'll learn:

Prerequisites:

Credits

Course Content

You might also like these resources:

Introduction to Cloudflare Workers

Create an eCommerce Store with Next.js and Stripe Checkout

Practical Git for Everyday Professional Use