How does GraphQL versioning differ from REST versioning?
Learn how GraphQL avoids v1/v2 bumps by evolving one schema with additive fields and @deprecated, and how that differs from REST versioning.
Expected Interview Answer
REST typically versions the whole API through the URL or headers (like /v1 and /v2), while GraphQL favors evolving a single, continuous schema by adding new fields and deprecating old ones instead of publishing new versions.
Because a GraphQL client asks only for the fields it needs, the server can add fields, arguments, and types without breaking existing queries. Old fields are marked with the @deprecated directive and kept until clients migrate, then removed. This continuous evolution avoids the parallel-maintenance cost of REST's v1/v2 endpoints, though it shifts the burden onto disciplined deprecation, monitoring field usage, and clear client communication.
- No breaking version bumps for additive changes
- Clients only fetch fields they request, so additions are safe
- @deprecated directive guides clients off old fields
- Field-usage analytics reveal when it is safe to remove
- Avoids maintaining multiple parallel endpoint versions
- Smoother, incremental migration for consumers
AI Mentor Explanation
Think of a scorecard app that keeps adding new stats columns like strike rate and dot-ball percentage. Old broadcasters who only read runs and wickets are untouched, while new ones opt into the extra columns. Retiring an outdated stat means flagging it as deprecated for a season before dropping it, never reprinting a whole new scorecard format each year.
Step-by-Step Explanation
Step 1
Start with a single schema
Expose one endpoint whose schema evolves, rather than /v1 and /v2 URLs.
Step 2
Add fields additively
Introduce new fields, arguments, and types; existing queries ignore what they do not request.
Step 3
Deprecate, do not delete
Mark outgoing fields with @deprecated(reason: ...) so clients see guidance in tooling.
Step 4
Measure field usage
Track which deprecated fields are still queried using resolver-level analytics or tracing.
Step 5
Remove when safe
Once usage hits zero and the window closes, delete the deprecated field from the schema.
What Interviewer Expects
- Understanding that GraphQL evolves one schema rather than bumping versions
- Knowledge of the @deprecated directive
- Awareness that clients request only the fields they need
- The role of field-usage analytics before removing fields
- Trade-offs versus REST's /v1 /v2 approach
Common Mistakes
- Claiming GraphQL has no versioning concerns at all
- Confusing additive changes with breaking changes
- Forgetting that field removal or type changes can still break clients
- Not mentioning the @deprecated directive
- Assuming URL versioning is required like REST
Best Answer (HR Friendly)
“REST usually creates whole new API versions like v1 and v2, but GraphQL keeps one evolving API where you simply add new fields and mark old ones as deprecated. Because each client only asks for the exact data it needs, additions do not break anyone, so version bumps are rarely necessary.”
Code Example
type User {
id: ID!
name: String! @deprecated(reason: "Use fullName instead")
fullName: String!
email: String!
}
# Old clients keep querying name; new clients request fullName.
# No /v2 endpoint is created.Follow-up Questions
- What kinds of schema changes are still breaking in GraphQL?
- How would you track whether a deprecated field is still in use?
- When, if ever, would you actually version a GraphQL API?
- How does the @deprecated directive surface in client tooling?
MCQ Practice
1. How does GraphQL typically handle API evolution compared to REST?
GraphQL favors a continuously evolving single schema, adding fields and marking old ones @deprecated, instead of separate versioned endpoints.
2. Which change to a GraphQL schema is generally safe (non-breaking)?
Adding a new field is additive; existing clients do not request it, so their queries are unaffected.
Flash Cards
How does GraphQL usually version? — It evolves a single schema with additive fields and @deprecated markers instead of new URLs.
What directive deprecates a GraphQL field? — @deprecated(reason: "..."), which surfaces guidance in client tooling.
Why are added fields safe in GraphQL? — Clients request only the fields they need, so new fields go unrequested and cannot break them.
What must you do before removing a deprecated field? — Confirm via field-usage analytics that no client still queries it.