How to deprecate GraphQL Enums

The deprecation flow of GraphQL is a great property of the technology. While many think the main benefit of a GraphQL API is the lack of waterfall request chains or lack of overfetching, I think the possibility to evolve the API is more important. You do that by using the GraphQL deprecation flow.

The GraphQL deprecation flow

When you want to make a breaking change to your GraphQL schema, you start by deprecating the part you want to get rid of. How you do this depends on your server implementation, in GraphQL Ruby you add deprecation_reason, and in regular GraphQL SDL you add the @deprecated directive. It is important that you write what the clients are supposed to do instead.

Avoid using GraphQL deprecations to signal deprecated features of your product. Clients should be able to take immediate action on schema deprecations, and not wait on decisions from the product department.

The next step is to deploy your changes, and start measuring the use of the deprecated part of the schema. The simplest way would be to log the use in the resolver code. The smart way is to use a tool like Hubburu which tracks usage automatically. If clients keep using the deprecated part, you can reach out to them and warn them about the upcoming change. Therefore it is important that you have a way of tracking the identity of the clients and their versions, connected to their usage.

Once the usage of the deprecated parts has stopped, you can safely remove it.

How to deprecate enums

Enums are a bit harder to deprecate than fields, mainly because enums can come in as variables. Enums can also be part of the document body (like query { users(sortBy: DESCENDING) { id } } where DESCENDING would be an enum, or be outgoing values from resolvers.

To follow up on deprecated fields, it is enough to track the operation documents, and you can see the fields which are being used. Enums require you to consider the earlier mentioned cases.

If the deprecation usage tracking solution you are using does not measure this kind of usage, you either have to risk breaking clients or resort to worse tracking solutions like logging. Hubburu has support for tracking all incoming enums. Enums going out from your server is in your control, so it is quite easy to stop sending that value.