Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

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 Enterprise best practices: Schema design course on .

Not an enterprise customer? Learn about GraphOS for Enterprise.

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 field 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 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 field 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 field?" 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 Clients & Operations table on the Insights page in GraphOS Studio can provide insight into what clients might still be using the deprecated fields.

In addition, schema checks will check any changes pushed for registered schemas against a recent window of tracing data to ensure that a deprecated field 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
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company