Handling Breaking Changes in GraphQL

Rate this content
Bookmark
Slides

Requirements change, but API contracts are forever - I wish! A breaking change is something that is not backwards compatible. This means that a consumer of your API would not be able to use the new version without making a code change themselves. We avoid breaking changes if possible, but there are cases when they are inevitable. It could be something small: like making a mandatory field optional. Or it could be something big: like removing a query or a mutation. In this talk we'll review the types of breaking changes you may encounter and how to deal with them gracefully.

Kadi Kraman
Kadi Kraman
22 min
08 Dec, 2022

Comments

Sign in or register to post your comment.

Video Summary and Transcription

This Talk discusses handling breaking changes in a GraphQL schema, including the use of the deprecated directive to tag fields that should no longer be used. It also covers the process of deploying GraphQL APIs and mobile apps, highlighting the challenges of mobile app release adoption. The Talk emphasizes the importance of making safe upgrades in mobile apps and provides strategies for detecting and handling breaking changes, such as using TypeScript and GraphQL Inspector. Overall, the Talk emphasizes the need to minimize user impact when introducing breaking changes in GraphQL schemas.

1. Introduction to Breaking Changes in GraphQL Schema

Short description:

Hello everyone, in this part, I will talk about handling breaking changes in a GraphQL schema. I will explain what a breaking change is and provide a code example to illustrate it. Let's get started!

Hello everyone, it is a pleasure to be here and it is a pleasure to talk about something that is very relevant to my work, which is handling breaking changes in a GraphQL schema.

So, just a quick intro about me. My name is Kadi Kraman, I'm currently the Director of Mobile Development at Formidable. If you've not heard of us, Formidable is a consultancy. We build websites, mobile apps, and of course, GraphQL APIs. In my five years in this company, I think almost every single project had a GraphQL API in it. So we've been doing this quite a bit. Back in 2002, my first GraphQL API was around 2017, and since then, I've worked with both small and large applications, and mostly as an API consumer.

So, because I build a lot of mobile applications, usually I've been the client of a GraphQL API. I would spend maybe 20 per cent of my time writing GraphQL, and 80 per cent of my time using GraphQL APIs. So, breaking changes is something that's very relevant to me because I'm the client that gets affected if breaking changes happen.

So, what is a breaking change? A breaking change in a GraphQL schema is basically an update that causes the API contract to change in a way that is not backwards compatible. Now, what does this actually mean? I'm going to show you using a code example. So, here we have a little schema. We have a query where you can query a user by an ID and it will return you a user type. And the user type has just the ID and the name in it. Both of them are mandatory fields. And if we look at what a query would look like. So, here on the right, we're going to query the user by ID, query the ID and the name, and we get exactly that data back. So, say that you had this user type in your current project and the client comes back to you and says, hey, we don't want to have our name as a single string. We want to have the first name and the last name separately. So, as a new requirement, you need to separate the name field into first name and last name. So, how would you go about it? You would be tempted to do something like this. So, here we've added the first name and last name which are both mandatory strings. But then, because we really don't use the name anymore, we can remove the name field. Now, this seems all well and good from the schema side, from the API side. When we look at the client side and query the same query that we did before, we are actually met with an error. And the error says cannot query field name on type user. And indeed, the name field no longer exists. Now, this is an example of a breaking change.

2. Handling Breaking Changes in GraphQL Schema

Short description:

A change that is not backwards compatible. Instead of deleting the field, we can add a deprecation notice using the deprecated directive. The deprecated directive allows you to tag a field in a schema as a deprecated field to communicate to your consumers that this field should no longer be used. It is part of the GraphQL spec and most GraphQL servers should be implementing it. Insomnia, a GraphQL client, provides an example of how deprecated fields are displayed in the schema. Now I will show you a way to introduce a breaking API change in a GraphQL API relatively safely by following the steps: add, deprecate, migrate, remove.

A change that is not backwards compatible. Because a query that worked on the previous version of this API no longer works because of this change. Let's look at how we would make this change backwards compatible. It's actually surprisingly simple. Instead of deleting the field, we can add a deprecation notice using the deprecated directive. Here you've seen next to the name field, I've added deprecated and also provided a reason. So in this case, it's deprecated in favor of first name and last name.

And here we can see that the previous query that queried just the ID and name still works and the new query that queries the first name and last name still works. Therefore, because both the previous and new queries work, this is a change that is backwards is compatible. The deprecated directive is really handy. It's basically it allows you to tag a field in a schema as a deprecated field to communicate to your consumers that this field should no longer be used. It is part of the GraphQL spec, which means that most GraphQL servers should be implementing it. The most important part, most IEDs, GraphQL tools, and clients that you might be using will pick up this notification and warn you if you're using a deprecated field.

Here I've added an example. This is from Insomnia, which is a GraphQL client that I use for querying. When I look at the schema and the user type in particular, we can see that the name now has an exclamation mark next to it. If I hover over it, it's telling me that the field name is now deprecated, and it's also giving me the deprecation message that I wrote. So it's deprecated in favor of first name and last name. Now there might be a reason, however, rarely, that you'd simply have to introduce a breaking API change. So I'm going to show you a way that you could introduce a breaking API change in a GraphQL API relatively safely. The key words you need to remember are add, deprecate, migrate, remove. Unfortunately, not a very good acronym. Let's go through these one by one to show you what each step means. So this is our starting state. We're going to start with this user type that we used before, just with the id and a name. And this is our application stack. So we're going to have a website, let's say that's an Xjs app. We're going to have an API. It's of course a GraphQL API. And because I build mobile apps, we're going to have a React Native app for iOS and Android in a third repository.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

From GraphQL Zero to GraphQL Hero with RedwoodJS
GraphQL Galaxy 2021GraphQL Galaxy 2021
32 min
From GraphQL Zero to GraphQL Hero with RedwoodJS
Top Content
We all love GraphQL, but it can be daunting to get a server up and running and keep your code organized, maintainable, and testable over the long term. No more! Come watch as I go from an empty directory to a fully fledged GraphQL API in minutes flat. Plus, see how easy it is to use and create directives to clean up your code even more. You're gonna love GraphQL even more once you make things Redwood Easy!
Local State and Server Cache: Finding a Balance
Vue.js London Live 2021Vue.js London Live 2021
24 min
Local State and Server Cache: Finding a Balance
Top Content
How many times did you implement the same flow in your application: check, if data is already fetched from the server, if yes - render the data, if not - fetch this data and then render it? I think I've done it more than ten times myself and I've seen the question about this flow more than fifty times. Unfortunately, our go-to state management library, Vuex, doesn't provide any solution for this.For GraphQL-based application, there was an alternative to use Apollo client that provided tools for working with the cache. But what if you use REST? Luckily, now we have a Vue alternative to a react-query library that provides a nice solution for working with server cache. In this talk, I will explain the distinction between local application state and local server cache and do some live coding to show how to work with the latter.
Get rid of your API schemas with tRPC
React Day Berlin 2022React Day Berlin 2022
29 min
Get rid of your API schemas with tRPC
Do you know we can replace API schemas with a lightweight and type-safe library? With tRPC you can easily replace GraphQL or REST with inferred shapes without schemas or code generation. In this talk we will understand the benefit of tRPC and how apply it in a NextJs application. If you want reduce your project complexity you can't miss this talk.
Batteries Included Reimagined - The Revival of GraphQL Yoga
GraphQL Galaxy 2021GraphQL Galaxy 2021
33 min
Batteries Included Reimagined - The Revival of GraphQL Yoga
The Guild has recently released Envelop - a new, modern GraphQL Server Framework and plugin system. In this talk I’ll share a brief overview of Envelop and why you should probably upgrade your existing GraphQL server to it.
Rock Solid React and GraphQL Apps for People in a Hurry
GraphQL Galaxy 2022GraphQL Galaxy 2022
29 min
Rock Solid React and GraphQL Apps for People in a Hurry
In this talk, we'll look at some of the modern options for building a full-stack React and GraphQL app with strong conventions and how this can be of enormous benefit to you and your team. We'll focus specifically on RedwoodJS, a full stack React framework that is often called 'Ruby on Rails for React'.

Workshops on related topic

Build with SvelteKit and GraphQL
GraphQL Galaxy 2021GraphQL Galaxy 2021
140 min
Build with SvelteKit and GraphQL
Top Content
Featured WorkshopFree
Scott Spence
Scott Spence
Have you ever thought about building something that doesn't require a lot of boilerplate with a tiny bundle size? In this workshop, Scott Spence will go from hello world to covering routing and using endpoints in SvelteKit. You'll set up a backend GraphQL API then use GraphQL queries with SvelteKit to display the GraphQL API data. You'll build a fast secure project that uses SvelteKit's features, then deploy it as a fully static site. This course is for the Svelte curious who haven't had extensive experience with SvelteKit and want a deeper understanding of how to use it in practical applications.

Table of contents:
- Kick-off and Svelte introduction
- Initialise frontend project
- Tour of the SvelteKit skeleton project
- Configure backend project
- Query Data with GraphQL
- Fetching data to the frontend with GraphQL
- Styling
- Svelte directives
- Routing in SvelteKit
- Endpoints in SvelteKit
- Deploying to Netlify
- Navigation
- Mutations in GraphCMS
- Sending GraphQL Mutations via SvelteKit
- Q&A
End-To-End Type Safety with React, GraphQL & Prisma
React Advanced Conference 2022React Advanced Conference 2022
95 min
End-To-End Type Safety with React, GraphQL & Prisma
Featured WorkshopFree
Sabin Adams
Sabin Adams
In this workshop, you will get a first-hand look at what end-to-end type safety is and why it is important. To accomplish this, you’ll be building a GraphQL API using modern, relevant tools which will be consumed by a React client.
Prerequisites: - Node.js installed on your machine (12.2.X / 14.X)- It is recommended (but not required) to use VS Code for the practical tasks- An IDE installed (VSCode recommended)- (Good to have)*A basic understanding of Node.js, React, and TypeScript
GraphQL for React Developers
GraphQL Galaxy 2022GraphQL Galaxy 2022
112 min
GraphQL for React Developers
Featured Workshop
Roy Derks
Roy Derks
There are many advantages to using GraphQL as a datasource for frontend development, compared to REST APIs. We developers in example need to write a lot of imperative code to retrieve data to display in our applications and handle state. With GraphQL you cannot only decrease the amount of code needed around data fetching and state-management you'll also get increased flexibility, better performance and most of all an improved developer experience. In this workshop you'll learn how GraphQL can improve your work as a frontend developer and how to handle GraphQL in your frontend React application.
Build a Headless WordPress App with Next.js and WPGraphQL
React Summit 2022React Summit 2022
173 min
Build a Headless WordPress App with Next.js and WPGraphQL
Top Content
WorkshopFree
Kellen Mace
Kellen Mace
In this workshop, you’ll learn how to build a Next.js app that uses Apollo Client to fetch data from a headless WordPress backend and use it to render the pages of your app. You’ll learn when you should consider a headless WordPress architecture, how to turn a WordPress backend into a GraphQL server, how to compose queries using the GraphiQL IDE, how to colocate GraphQL fragments with your components, and more.
Relational Database Modeling for GraphQL
GraphQL Galaxy 2020GraphQL Galaxy 2020
106 min
Relational Database Modeling for GraphQL
Top Content
WorkshopFree
Adron Hall
Adron Hall
In this workshop we'll dig deeper into data modeling. We'll start with a discussion about various database types and how they map to GraphQL. Once that groundwork is laid out, the focus will shift to specific types of databases and how to build data models that work best for GraphQL within various scenarios.
Table of contentsPart 1 - Hour 1      a. Relational Database Data Modeling      b. Comparing Relational and NoSQL Databases      c. GraphQL with the Database in mindPart 2 - Hour 2      a. Designing Relational Data Models      b. Relationship, Building MultijoinsTables      c. GraphQL & Relational Data Modeling Query Complexities
Prerequisites      a. Data modeling tool. The trainer will be using dbdiagram      b. Postgres, albeit no need to install this locally, as I'll be using a Postgres Dicker image, from Docker Hub for all examples      c. Hasura
Building GraphQL APIs on top of Ethereum with The Graph
GraphQL Galaxy 2021GraphQL Galaxy 2021
48 min
Building GraphQL APIs on top of Ethereum with The Graph
WorkshopFree
Nader Dabit
Nader Dabit
The Graph is an indexing protocol for querying networks like Ethereum, IPFS, and other blockchains. Anyone can build and publish open APIs, called subgraphs, making data easily accessible.

In this workshop you’ll learn how to build a subgraph that indexes NFT blockchain data from the Foundation smart contract. We’ll deploy the API, and learn how to perform queries to retrieve data using various types of data access patterns, implementing filters and sorting.

By the end of the workshop, you should understand how to build and deploy performant APIs to The Graph to index data from any smart contract deployed to Ethereum.