Evolving a GraphQL Schema incl. Breaking Changes without affecting a Single User
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.