Versioning Graphql

title: "Versioning GraphQL APIs — Schema Evolution Without Breaking Clients" description: "GraphQL API versioning relies on schema evolution through deprecation and additive changes, avoiding traditional version numbers by leveraging GraphQL's type system." date: 2026-06-28 lastmod: 2026-06-28 weight: 24 tags: [apis, versioning] }

GraphQL API versioning uses schema evolution with deprecation directives and additive field changes, leveraging GraphQL's strong type system to avoid breaking clients.

What You'll Learn

• GraphQL deprecation with @deprecated
• Additive schema evolution
• When to introduce a new GraphQL endpoint

Why It Matters

GraphQL's client-driven queries naturally support additive evolution. Clients only request fields they use, so adding fields doesn't break existing queries.

Code Examples

# Schema evolution with deprecation
type User {
  id: ID!
  name: String!
  email: String @deprecated(reason: "Use emailAddress instead")
  emailAddress: String  # New field, safe addition
  profile: Profile
}

type Profile {
  displayName: String!
  avatar: String
  # New field added safely
  bio: String
  joinDate: String @deprecated(reason: "Use createdAt on User")
  createdAt: String!
}

# Query additions
type Query {
  users: [User!]!
  # New query - additive change
  searchUsers(query: String!): [User!]!
}

# GraphQL deprecation in schema
import graphene

class User(graphene.ObjectType):
    id = graphene.ID()
    name = graphene.String()
    email = graphene.String(deprecation_reason="Use emailAddress")
    email_address = graphene.String()

    def resolve_email_address(self, info):
        return self.email

# When to introduce new version
# Option 1: Add new fields with @deprecated on old ones
# Option 2: Create a new endpoint at /graphql/v2

class UserV2(graphene.ObjectType):
    id = graphene.ID()
    full_name = graphene.String()  # Renamed from name
    email_address = graphene.String()  # Renamed from email
    created_at = graphene.String()  # New field

// Apollo Server version handling
const typeDefs = `
  type User {
    id: ID!
    name: String!
    email: String @deprecated(reason: "Use emailAddress")
    emailAddress: String
  }

  type Query {
    users: [User!]!
  }
`;

// Versioned resolvers
const resolvers = {
  User: {
    emailAddress: (parent) => parent.email,
    email: (parent) => {
      if (parent._legacy) {
        return parent.email;
      }
      return null;  // @deprecated field returns null
    }
  }
};

Common Mistakes

1. Creating v2 GraphQL Endpoint Too Early

GraphQL rarely needs versioned endpoints. Use schema deprecation instead.

2. Not Using @deprecated

Fields should be deprecated for at least one release cycle before removal.

3. Breaking Nullability Contracts

Changing String! to String or vice versa breaks clients.

4. Removing Enum Values

Old enum values must stay. Add new values, deprecate old ones.

5. Changing Input Types

Input types are more breaking than output types. Be careful.

Practice Questions

1. Why does GraphQL handle versioning differently than REST?
2. How do you deprecate a field in GraphQL?
3. When should you create a new GraphQL endpoint?
4. What happens when you remove a field in GraphQL?
5. How do nullable vs non-nullable affect versioning?

Answers:

1. GraphQL clients request specific fields, so adding fields doesn't break them.
2. Using the @deprecated(reason: "...") directive on the field.
3. Rarely. Only for major architectural changes like auth system overhaul.
4. Client queries for that field will error.
5. Changing nullability is always breaking. Adding non-null fields to existing types breaks.

Challenge: Evolve a GraphQL schema through three versions using only @deprecated and additive changes. Show that old queries still work.

FAQ