Best Practices : Versioning GraphQL APIs #884

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

site/learn/BestPractice-Versioning.md

+	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

site/learn/BestPractice-Versioning.md

+	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

site/learn/BestPractice-Versioning.md

+	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

site/learn/BestPractice-Versioning.md

+}
+```
+
+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

site/learn/BestPractice-Versioning.md

+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

site/learn/BestPractice-Versioning.md

+### 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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Best Practices : Versioning GraphQL APIs #884

Best Practices : Versioning GraphQL APIs #884

nisarg1499 commented Jun 28, 2020

carolstran commented Aug 20, 2020

nisarg1499 commented Aug 20, 2020

ekampf Nov 17, 2020

nisarg1499 Mar 5, 2021 •

edited

Loading

benjie left a comment •

edited

Loading

benjie Nov 18, 2020

nisarg1499 Mar 5, 2021

benjie Nov 18, 2020

nisarg1499 Mar 5, 2021

benjie Nov 18, 2020

benjie Nov 18, 2020

benjie Nov 18, 2020

nisarg1499 Mar 5, 2021

nisarg1499 Mar 27, 2021

nisarg1499 commented Dec 7, 2020

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

edited

Loading

nisarg1499 commented Feb 27, 2021

nisarg1499 commented Mar 5, 2021

nisarg1499 commented Mar 5, 2021

benjie commented Mar 15, 2021

	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.

Best Practices : Versioning GraphQL APIs #884

Are you sure you want to change the base?

Best Practices : Versioning GraphQL APIs #884

Conversation

nisarg1499 commented Jun 28, 2020

carolstran commented Aug 20, 2020

nisarg1499 commented Aug 20, 2020

Choose a reason for hiding this comment

nisarg1499 Mar 5, 2021 • edited Loading

Choose a reason for hiding this comment

benjie left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nisarg1499 commented Dec 7, 2020

linux-foundation-easycla bot commented Feb 27, 2021 • edited Loading

nisarg1499 commented Feb 27, 2021

nisarg1499 commented Mar 5, 2021

nisarg1499 commented Mar 5, 2021

benjie commented Mar 15, 2021

nisarg1499 Mar 5, 2021 •

edited

Loading

benjie left a comment •

edited

Loading

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

edited

Loading