Hot Chocolatev12
This is documentation for v12, which is no longer actively maintained.
For up-to-date documentation, see the latest stable version.

Versioning

Whilst we could version our GraphQL API similar to REST, i.e. /graphql/v1, it is not a best practice and often unnecessary.

Many changes to a GraphQL schema are non-breaking. We can freely add new types and extend existing types with new fields. This does not break existing queries. However removing a field or changing its nullability does.

Instead of removing a field immediately and possibly breaking existing consumers of our API, fields can be marked as deprecated in our schema. This signals to consumers that the field will be removed in the future and they need to adapt before then.

SDL
type Query {
users: [User] @deprecated("Use the `authors` field instead")
authors: [User]
}

Deprecating fields

Fields can be deprecated like the following.

C#
public class Query
{
[GraphQLDeprecated("Use the `authors` field instead")]
public User[] GetUsers()
{
// Omitted code for brevity
}
}

Note: It is currently not possible to deprecate input values, such as arguments.