Docs
Launch GraphOS Studio

Schema deprecations

Gracefully manage type and field deprecations

schema-design

💡 TIP

If you're an enterprise customer looking for more material on this topic, try the

course on .

Not an enterprise customer?

Leverage SDL and tooling to manage deprecations

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

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

, should be applied when deprecating or enum values in a schema. 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 has been deprecated as follows:

extend type Query {
"""
Fetch a simple list of products with an offset
"""
topProducts(
"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.
"""
products(
"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 schema has been updated with new @deprecated , it's important to communicate the deprecations beyond the as well. Using a 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

on the Insights page in
GraphOS Studio
can provide insight into what clients might still be using the deprecated .

In addition,

will check any changes pushed for registered schemas 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.

Next
Home
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company