Best Practices : Versioning GraphQL APIs by nisarg1499 · Pull Request #884 · graphql/graphql.github.io

nisarg1499 · 2020-06-28T09:02:19Z

I have added Versioning of GraphQL APIs under Best Practices section.
Topics added in the writing :

Versioning of REST APIs
Versioning GraphQL APIs
Example of Shopify : how they have versioned their GraphQL APIs
Some more info and tools for schema validation(useful for versioning)

Mentor for this writing : @Urigo

carolstran · 2020-08-20T12:59:14Z

👋🏼 Looping this PR into the discussion going on #41. That way, if people find their way there through the GSoD proposals then they'll know that you're already working on this one 😊

nisarg1499 · 2020-08-20T14:43:54Z

👋🏼 Looping this PR into the discussion going on #41. That way, if people find their way there through the GSoD proposals then they'll know that you're already working on this one 😊

@carolstran Can you review this PR? The PR is ready for review.

ekampf · 2020-11-17T16:24:24Z

+	name: String!
+	Username : String!
+	birthDate : DateTime!
+	lastLoginHistory : NewDateTime!


but... this would be a breaking change for clients?

@ekampf How? I think we can evolve schema by referencing schemas to others. Any specifics why this will be a breaking change?

benjie

Searching for "deprecated", "deprecate" and "deprecation" with the graphql.org search bar doesn't have any matches so it's clear that we do need some content like this; so thanks for opening the conversation 👍 However, I don't think we should add a section called "Versioning" as versioning does go against the generally agreed best practices of GraphQL.

I think we could take a slightly different tact and talk more about deprecation, explaining what changes are allowed to be made without "breaking" the schema, and maybe note that this approach which avoids explicit versioning allows your schema to evolve over time without ever breaking older clients/queries.

There's been extensive discussion about Shopify's versioning pattern in recent GraphQL Spec WGs; here's some relevant notes if you're interested (you can also view the YouTube recording): https://github.com/graphql/graphql-wg/blob/c3dda0548c8b7114ee693bf7334ba714575dce70/notes/2020-09-03.md#allowing-deprecation-of-inputs-10m-evan (in general the GraphQL Spec WG seem reluctant to encourage this form of versioning)

The examples in this PR use firstName, middleName and lastName which really aren't universal concepts and I'm very hesitant to add them to the GraphQL documentation; read more here: https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/ Can you come up with an example that is more universal?

benjie · 2020-11-18T09:56:42Z

+	id: Int!,
+	firstName : String!,
+	lastName : String!


No need for trailing commas, and the whitespace is inconsistent. May I recommend piping this file through prettier --prose-wrap always to automatically format the markdown (including automatically formatting the GraphQL snippets).

Suggested change

id: Int!,

firstName : String!,

lastName : String!

id: Int!

firstName: String!

lastName: String!

I'll reformat the file through prettier in VS code. I hope that will fix all format issues.

benjie · 2020-11-18T09:58:58Z

+	Id : Int!,
+	firstName : String!,
+	middleName : String!
+	lastName : String,


Few formatting issues, id became capitalised, and lastName becoming nullable was a breaking change.

Suggested change

Id : Int!,

firstName : String!,

middleName : String!

lastName : String,

id: Int!

firstName: String!

middleName: String

lastName: String!

Agreed. It was just a typo by me. Fixed in next commit.

benjie · 2020-11-18T10:00:41Z

+}
+```
+
+Here we have added the middleName parameter which is mandatory and have changed lastName to optional.


You can change an optional field to required, but you cannot change a required field to optional (that's a breaking change). The term field is the correct term to use here (rather than parameter).

Suggested change

Here we have added the middleName parameter which is mandatory and have changed lastName to optional.

Here we have added the `middleName` field which is optional.

benjie · 2020-11-18T10:03:52Z

+Here we have added the middleName parameter which is mandatory and have changed lastName to optional.
+
+
+* The best practice is to use “@deprecated(reason)” defined in the schema. By using this the client can know which filed to use and which one is deprecated. This will not define the version number as the semantic versioning does. The deprecated fields will be shown by the GraphQL Explorer.


The wording of this bullet needs revisiting. Separately, I think it's probably better for it to be a section title such as "The 'deprecated' directive" rather than a bullet.

benjie · 2020-11-18T10:04:29Z

+### More info on Versioning
+There are few other best practices for versioning GraphQL APIs.
+Version constraints can be added to the query which will tell that the field will be resolved by which version. Using version constraints we can access different fields of different versions. For example, the query will look like : 
+```graphql
+query {
+	account(id : 5){
+		old : profilePhoto(versionContraint : “^0.1”)
+		new : profilePhoto(versionContraint : “^0.2”)
+	}
+}
+```
+
+We can define the versions in the schema and query can be written as above to access the fields of different versions.


I've never seen this recommended as a best practice before (and am very dubious); could you share details of where you've seen this recommended as a best practice? Also typographic quotes have slipped in where you meant straight quotes.

It's actually tagging+semantic versioning. I do not remember where I read this, but I'll try to find it.

@benjie Should I keep this point?

nisarg1499 · 2020-12-07T09:55:31Z

@benjie Thanks for reviewing. I will look into your comments and make changes wherever required.

linux-foundation-easycla · 2021-02-27T15:03:21Z

The committers are authorized under a signed CLA.

✅ Nisarg Shah (b89e2fe, 39d20eb, 7903da4, a2b05c5, d0dd267, 4663f3e)

nisarg1499 · 2021-02-27T15:11:19Z

@benjie Sorry for the delay. In a couple of days I will try to make all suggested changes and then you can review it.

nisarg1499 · 2021-03-05T18:34:34Z

The examples in this PR use firstName, middleName and lastName which really aren't universal concepts and I'm very hesitant to add them to the GraphQL documentation; read more here: https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/ Can you come up with an example that is more universal?

@benjie Do you have any ideas/examples which we can added instead of firstName and lastName? Actually I added considering profile section in mind. Most of the products have profile sections. That's why.

nisarg1499 · 2021-03-05T19:00:08Z

There's been extensive discussion about Shopify's versioning pattern in recent GraphQL Spec WGs; here's some relevant notes if you're interested (you can also view the YouTube recording):

@benjie Can you share the youtube link? I tried searching but was not able to find it. I'll capture main points from video and add in the page.

benjie · 2021-03-15T13:32:38Z

@nisarg1499 Sure; videos are here:

https://www.youtube.com/channel/UCERcwLeheOXp_u61jEXxHMA

Notes are here:

https://github.com/graphql/graphql-wg/tree/main/notes

martinbonnin · 2026-07-20T11:42:23Z

I'm going to close this one in favor of #2318.
We now have a dedicated "versioning" page at https://graphql.org/learn/governance-versioning/

If you believe some guidance is missing or could be improved, please open a new pull request.

nisarg1499 added 5 commits June 28, 2020 13:43

Added versioning in best practices with some content

b89e2fe

Content on versioning

39d20eb

More info on versioning

7903da4

info on evolution of graphql schema

a2b05c5

info of tools for managing schemas

d0dd267

carolstran added the ✏️ Editorial label Sep 3, 2020

ekampf reviewed Nov 17, 2020

View reviewed changes

benjie requested changes Nov 18, 2020

View reviewed changes

making branch up-to-date

4663f3e

Merge remote-tracking branch 'origin/source' into versioning

6b7ac7a

added some required changes

d81a3b7

martinbonnin added the 💤 stale? label Jun 23, 2026

martinbonnin closed this Jul 20, 2026

	Here we have added the middleName parameter which is mandatory and have changed lastName to optional.
	Here we have added the `middleName` field which is optional.

		Here we have added the middleName parameter which is mandatory and have changed lastName to optional.


		* The best practice is to use “@deprecated(reason)” defined in the schema. By using this the client can know which filed to use and which one is deprecated. This will not define the version number as the semantic versioning does. The deprecated fields will be shown by the GraphQL Explorer.

Uh oh!

Conversation

nisarg1499 commented Jun 28, 2020

Uh oh!

carolstran commented Aug 20, 2020

Uh oh!

nisarg1499 commented Aug 20, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nisarg1499 Mar 5, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nisarg1499 commented Dec 7, 2020

Uh oh!

linux-foundation-easycla Bot commented Feb 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nisarg1499 commented Feb 27, 2021

Uh oh!

nisarg1499 commented Mar 5, 2021

Uh oh!

nisarg1499 commented Mar 5, 2021

Uh oh!

benjie commented Mar 15, 2021

Uh oh!

martinbonnin commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nisarg1499 Mar 5, 2021 •

edited

Loading

benjie left a comment •

edited

Loading

linux-foundation-easycla Bot commented Feb 27, 2021 •

edited

Loading