Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Schema deprecations


Leverage SDL and tooling to manage deprecations

Your graph governance group should outline a company-wide rollover strategy to gracefully handle type and field deprecations throughout the unified graph.

GraphQL APIs can be versioned, but at Apollo, we have seen that it is far more common for organizations to leverage GraphQL's inherently evolutionary nature and iterate their APIs on a rapid and incremental basis. Doing so, however, requires clear communication with API consumers, and especially when deprecations are required.

Use the @deprecated type system directive

As a first step, the @deprecated , which is defined in the GraphQL specification, should be applied when deprecating s or enum values in a . Its single reason can also provide the API consumer some direction about what to do instead of using that or enum value. For instance, this example we can indicate that a related topProducts query has been deprecated as follows:

extend type Query {
Fetch a simple list of products with an offset
"How many products to retrieve per page."
first: Int = 5
): [Product] @deprecated(reason: "Use `products` instead.")
Fetch a paginated list of products based on a filter type.
"How many products to retrieve per page."
first: Int = 5
"Begin paginating results after a product ID."
after: Int = 0
"Filter products based on a type."
type: ProductType = LATEST
): ProductConnection

Use field usage metrics to assess when it's safe to remove fields

After a service's has been updated with new @deprecated s, it's important to communicate the deprecations beyond the as well. Using a dedicated Slack channel or team meetings might serve as appropriate communication channels for such notices, and they should be delivered with any additional migration instructions for client teams.

At this point, a crucial question still remains: "When will it be safe to remove the deprecated ?" To answer this question with certainty that you won't cause any breaking changes to client applications, you must lean on your observability tooling.

Specifically, the Requested by operations in the last day column in the s page in GraphOS Studio can provide insight into what clients might still be using the deprecated s so appropriate follow-ups can be actioned.

In addition, schema checks will check any changes pushed for registered s against a recent window of tracing data to ensure that a deprecated rollover can be completed without causing any breaking changes to existing clients. It's common to require that clients identify themselves so that you can reach out to them before making a breaking change.

Edit on GitHubEditForumsDiscord