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

Nik Graf
InstructorNik Graf
Share this video with your friends

Social Share Links

Send Tweet
Published 5 years ago
Updated 4 years ago

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.

Instructor: [0:00] What to do in case you ended up in a situation where we have a field like image returning a string, but we want to move to image returning full image?

[0:10] First, our focus should still be on providing value as soon as possible. Therefore, we add image object returning the new image type. To get it with this change, we can ship deprecating the field image. Then, deploy all these changes together.

[0:35] Now, we have to wait. How long? Depends on how quick we can make sure all our users use clients that make use of image object. If we only have a web client, this can happen rather quick, but in case the API is used by mobile clients, it might take a while until all our users upgraded to a new version.

[0:57] By the way, there is no need to guess this or track this based on the app version usage. Why? Because in GraphQL there's no way to query for all fields automatically. If we want to have a field in the response, we have to define it explicitly in the query, which means on every request we can track which fields are requested and verify if a field hasn't been requested for a while.

[1:24] Once the field image is not used anymore, we can move on to the next step. We remove image string and, at the same time, add image image. Basically, we replace one with the other. In addition, we add a deprecation to image object referring that the field image should be used. This is great, since we're already very close to the desired outcome.

[1:51] Last but not least, we eventually can remove the field image object, but again, only once all our users using clients that use the field image instead of image object.

[2:03] In summary, with enough time and multiple deploys, you can make breaking changes in a GraphQL schema without ever affecting a single user.

~ 3 minutes ago

Member comments are a way for members to communicate, interact, and ask questions about a lesson.

The instructor or someone from the community might respond to your question Here are a few basic guidelines to commenting on egghead.io

Be on-Topic

Comments are for discussing a lesson. If you're having a general issue with the website functionality, please contact us at support@egghead.io.

Avoid meta-discussion

  • This was great!
  • This was horrible!
  • I didn't like this because it didn't match my skill level.
  • +1 It will likely be deleted as spam.

Code Problems?

Should be accompanied by code! Codesandbox or Stackblitz provide a way to share code and discuss it in context

Details and Context

Vague question? Vague answer. Any details and context you can provide will lure more interesting answers!

Markdown supported.
Become a member to join the discussionEnroll Today