From b89e2fe54068b48f513a3da18045b09d108641c0 Mon Sep 17 00:00:00 2001 From: Nisarg Shah Date: Sun, 28 Jun 2020 13:43:30 +0530 Subject: [PATCH 1/6] Added versioning in best practices with some content --- site/learn/BestPractice-ThinkingInGraphs.md | 2 +- site/learn/BestPractice-Versioning.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 site/learn/BestPractice-Versioning.md diff --git a/site/learn/BestPractice-ThinkingInGraphs.md b/site/learn/BestPractice-ThinkingInGraphs.md index fcc3a637b0..eb684f4019 100644 --- a/site/learn/BestPractice-ThinkingInGraphs.md +++ b/site/learn/BestPractice-ThinkingInGraphs.md @@ -3,7 +3,7 @@ title: Thinking in Graphs layout: ../_core/DocsLayout category: Best Practices permalink: /learn/thinking-in-graphs/ -next: /learn/serving-over-http/ +next: /learn/versioning/ --- ## It's Graphs All the Way Down [\*](https://en.wikipedia.org/wiki/Turtles_all_the_way_down) diff --git a/site/learn/BestPractice-Versioning.md b/site/learn/BestPractice-Versioning.md new file mode 100644 index 0000000000..95f3386e4f --- /dev/null +++ b/site/learn/BestPractice-Versioning.md @@ -0,0 +1,20 @@ +--- +title: Versioning GraphQL APIs +layout: ../_core/DocsLayout +category: Best Practices +permalink: /learn/versioning/ +next: /learn/serving-over-http/ +--- + +## All About Versioning +> Don't let your application break by some breaking changes, Version your APIs + +After a certain period of time, applications and softwares get challenged with some changes in users and business needs. Due to which stability is not compatible with the system while changing only some parts. This is where versioning comes into picture. Versioning of API is done to update the existing API and make it compatible with the updated needs and services. Any change in the existing feature can break the application and so the new versions of API should be developed. + +### Versioning of REST +Now let’s have a look on versioning of RESTful API. You’ll wonder why we are talking about RESTful APIs. But gradually you will understand how versioning of GraphQL is much simpler and beautiful than REST. There are many best practices and strategies for REST API versioning such as + +* URI Versioning : /api/v1 +* Query Parameters : /api?version=1 +* Custom Headers : Accept-version : v1 + From 39d20eb1750bb57a46b3a40c063a0f779545f928 Mon Sep 17 00:00:00 2001 From: Nisarg Shah Date: Sun, 28 Jun 2020 14:24:32 +0530 Subject: [PATCH 2/6] Content on versioning --- site/learn/BestPractice-Versioning.md | 49 +++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/site/learn/BestPractice-Versioning.md b/site/learn/BestPractice-Versioning.md index 95f3386e4f..9c28cba51a 100644 --- a/site/learn/BestPractice-Versioning.md +++ b/site/learn/BestPractice-Versioning.md @@ -18,3 +18,52 @@ Now let’s have a look on versioning of RESTful API. You’ll wonder why we are * Query Parameters : /api?version=1 * Custom Headers : Accept-version : v1 +In most of the cases, uri versioning is used for versioning REST API. The client uses a specific version of API for implementations. + + +### Let's have a look at GraphQL +For GraphQL, you introduce or deprecate the fields or schema instead of versioning. While using GraphQL, one key point is that the query itself decides what response client wants. So there will be only one endpoint while using GraphQL API. We can say that instead of versioning, we are just modifying the existing schema. + +Let’s understand by an example. +We have a schema named user, which had fields such as id, firstName and lastName. +```graphql +type User { + id: Int!, + firstName : String!, + lastName : String! +} +``` + +In the above schema all fields are required. But in the next version we can add a variable and can also change the requirements. Such as : +```graphql +type User { + Id : Int!, + firstName : String!, + middleName : String! + lastName : String, +} +``` + +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. + +### Example of Shopify +Shopify versioned their GraphQL APIs using the url versioning approach and made their graphql endpoint such as “/api/{ version }/graphql.json”. [Here](https://shopify.dev/concepts/about-apis/versioning#the-api-version-release-schedule) is the document of shopify. They deprecate the fields and instead name the new variable as newVariablev2. + + +### 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. + From 7903da4ef16ea02ec5f2a7b19e7f166a11341be5 Mon Sep 17 00:00:00 2001 From: Nisarg Shah Date: Sun, 28 Jun 2020 14:26:03 +0530 Subject: [PATCH 3/6] More info on versioning --- site/learn/BestPractice-Versioning.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/site/learn/BestPractice-Versioning.md b/site/learn/BestPractice-Versioning.md index 9c28cba51a..1f6290d202 100644 --- a/site/learn/BestPractice-Versioning.md +++ b/site/learn/BestPractice-Versioning.md @@ -67,3 +67,12 @@ query { We can define the versions in the schema and query can be written as above to access the fields of different versions. +### Some tools +There are many tools which are used for schema validation and tracking schema versions. Some of the tools are `Apollo Graph Manager` and `GraphQL Inspector`. Schema can be validated using these tools and you can track all the schema changes. + +Using [Apollo Graph Manager](https://www.apollographql.com/docs/graph-manager/), you will be able to validate the schema and get the changes done in schema. For example : you will get to know which field is deprecated, for what reason and which fields are added new, etc. You will be able to validate the schema and check if anything is breaking or not. And you will also be able to know some detailed schema changes provided by this tool. + +Using [GraphQL Inspector](https://graphql-inspector.com/), you can detect the changes which can be breaking changes for the current schema. You are able to know the restriction changes in fields as well as addition/subtraction in fields. A complete difference is provided between old schema and new schema. And by that you can get to know the differences in form of non-breaking change, dangerous change and breaking change. + +### Conclusion +By this way we can version the GraphQL APIs and just move to the game of managing fields instead of versioning. It’s as simple as if you don’t want any field, then just drop it and add necessary fields with appropriate roles. From a2b05c5f8e565205fcaee1f9a27c6027b466309b Mon Sep 17 00:00:00 2001 From: nisarg1499 Date: Mon, 13 Jul 2020 01:54:18 +0530 Subject: [PATCH 4/6] info on evolution of graphql schema --- site/learn/BestPractice-Versioning.md | 40 +++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/site/learn/BestPractice-Versioning.md b/site/learn/BestPractice-Versioning.md index 1f6290d202..fdf3ca5068 100644 --- a/site/learn/BestPractice-Versioning.md +++ b/site/learn/BestPractice-Versioning.md @@ -49,9 +49,6 @@ Here we have added the middleName parameter which is mandatory and have changed * 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. -### Example of Shopify -Shopify versioned their GraphQL APIs using the url versioning approach and made their graphql endpoint such as “/api/{ version }/graphql.json”. [Here](https://shopify.dev/concepts/about-apis/versioning#the-api-version-release-schedule) is the document of shopify. They deprecate the fields and instead name the new variable as newVariablev2. - ### More info on Versioning There are few other best practices for versioning GraphQL APIs. @@ -67,6 +64,43 @@ query { We can define the versions in the schema and query can be written as above to access the fields of different versions. +### Evolution of Schema +This is definitely different from versioning, but this will be helpful to build schemas which can be evolved with time without making breaking changes. Schema can be evolved by making changes such as adding/removing fields, structures, types, etc. While making these changes, there can be some points which will restrict the schema while evolving and then @deprecated needs to be used as a last resort. For example there is a schema : +```graphql +type User{ + id: String! + name: String! + Username : String! + birthDate : DateTime! + lastLoginHistory : [DateTime]! +} + +``` +In the above schema we have one field named lastLoginHistory which stores the DateTime fields as a list. Now there needs some changes in the schema and some additional data needs to be added in lastLoginHistory. For that we need to add another field to the User schema. These changes will add many fields and this could make the schema lengthier and worse. + +But rather than this, we can build a schema for storing lastLoginHistory data and we can use that schema referenced to the User schema. +```graphql +type NewDateTime : { + lastLoginTime : DateTime! + lastLoginPeriodLength : Time! +} +``` +``` graphql +type User{ + id: String! + name: String! + Username : String! + birthDate : DateTime! + lastLoginHistory : NewDateTime! +} +``` +This way schemas can be evolved and can be maintained in a better way. Non-required fields should be deprecated but also the new fields should be introduced in that period and the old fields should be removed in such a way that no breaking changes occur. + + + +### Example of Shopify +Shopify versioned their GraphQL APIs using the url versioning approach and made their graphql endpoint such as “/api/{ version }/graphql.json”. [Here](https://shopify.dev/concepts/about-apis/versioning#the-api-version-release-schedule) is the document of shopify. They deprecate the fields and instead name the new variable as newVariablev2. + ### Some tools There are many tools which are used for schema validation and tracking schema versions. Some of the tools are `Apollo Graph Manager` and `GraphQL Inspector`. Schema can be validated using these tools and you can track all the schema changes. From d0dd267f8d2b4149f7e86bfba8d2fe02c67a8197 Mon Sep 17 00:00:00 2001 From: nisarg1499 Date: Thu, 16 Jul 2020 03:29:44 +0530 Subject: [PATCH 5/6] info of tools for managing schemas --- site/learn/BestPractice-Versioning.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/site/learn/BestPractice-Versioning.md b/site/learn/BestPractice-Versioning.md index fdf3ca5068..4dfddaf019 100644 --- a/site/learn/BestPractice-Versioning.md +++ b/site/learn/BestPractice-Versioning.md @@ -97,16 +97,19 @@ type User{ This way schemas can be evolved and can be maintained in a better way. Non-required fields should be deprecated but also the new fields should be introduced in that period and the old fields should be removed in such a way that no breaking changes occur. - ### Example of Shopify Shopify versioned their GraphQL APIs using the url versioning approach and made their graphql endpoint such as “/api/{ version }/graphql.json”. [Here](https://shopify.dev/concepts/about-apis/versioning#the-api-version-release-schedule) is the document of shopify. They deprecate the fields and instead name the new variable as newVariablev2. -### Some tools -There are many tools which are used for schema validation and tracking schema versions. Some of the tools are `Apollo Graph Manager` and `GraphQL Inspector`. Schema can be validated using these tools and you can track all the schema changes. +### Some tools for managing schemas +There are some tools which are used for schema validation, tracking schema versions, identifying unused types and many more. Some of the tools are `Apollo Graph Manager` and `GraphQL Inspector`. Schema can be validated using these tools and you can track all the schema changes. Using [Apollo Graph Manager](https://www.apollographql.com/docs/graph-manager/), you will be able to validate the schema and get the changes done in schema. For example : you will get to know which field is deprecated, for what reason and which fields are added new, etc. You will be able to validate the schema and check if anything is breaking or not. And you will also be able to know some detailed schema changes provided by this tool. +Apollo schema registry can track the changes of the schema and also gives the option to create variants of the schema. Also you can trace your GraphQL server by getting the report of which operations are being executed, which clients are executing which operations, which parts of schema are most used and which of the resolvers are used most. + +Now let’s have a look at GraphQL Inspector which also provides some similar functionalities. -Using [GraphQL Inspector](https://graphql-inspector.com/), you can detect the changes which can be breaking changes for the current schema. You are able to know the restriction changes in fields as well as addition/subtraction in fields. A complete difference is provided between old schema and new schema. And by that you can get to know the differences in form of non-breaking change, dangerous change and breaking change. +Using [GraphQL Inspector](https://graphql-inspector.com/), you can detect the changes which can be breaking changes for the current schema. You are able to know the restriction changes in fields as well as addition/subtraction in fields. A complete difference is provided between old schema and new schema. And by that you can get to know the differences in form of non-breaking change, dangerous change and breaking change. +In addition you can get the idea of coverage of the schema and can track which part of the schema is used, and by how many times. If any of the fields are deprecated, then the usage of those fields as well as checking of errors can be done using GraphQL Inspector. ### Conclusion By this way we can version the GraphQL APIs and just move to the game of managing fields instead of versioning. It’s as simple as if you don’t want any field, then just drop it and add necessary fields with appropriate roles. From d81a3b772874cdf475fe9d9d22db7761d44c10c8 Mon Sep 17 00:00:00 2001 From: nisarg1499 Date: Sat, 6 Mar 2021 00:05:22 +0530 Subject: [PATCH 6/6] added some required changes --- src/content/learn/BestPractice-Versioning.md | 114 +++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 src/content/learn/BestPractice-Versioning.md diff --git a/src/content/learn/BestPractice-Versioning.md b/src/content/learn/BestPractice-Versioning.md new file mode 100644 index 0000000000..6246784531 --- /dev/null +++ b/src/content/learn/BestPractice-Versioning.md @@ -0,0 +1,114 @@ +--- +title: Versioning GraphQL APIs +layout: docs +category: Best Practices +permalink: /learn/versioning/ +next: /learn/serving-over-http/ +--- + +## All About Versioning +> Don't let your application break by some breaking changes, Version your APIs + +After a certain period of time, applications and softwares get challenged with some changes in users and business needs. Due to which stability is not compatible with the system while changing only some parts. This is where versioning comes into picture. Versioning of API is done to update the existing API and make it compatible with the updated needs and services. Any change in the existing feature can break the application and so the new versions of API should be developed. + +### Versioning of REST +Now let’s have a look on versioning of RESTful API. You’ll wonder why we are talking about RESTful APIs. But gradually you will understand how versioning of GraphQL is much simpler and beautiful than REST. There are many best practices and strategies for REST API versioning such as + +* URI Versioning : /api/v1 +* Query Parameters : /api?version=1 +* Custom Headers : Accept-version : v1 + +In most of the cases, uri versioning is used for versioning REST API. The client uses a specific version of API for implementations. + + +### Let's have a look at GraphQL +For GraphQL, you introduce or deprecate the fields or schema instead of versioning. While using GraphQL, one key point is that the query itself decides what response client wants. So there will be only one endpoint while using GraphQL API. We can say that instead of versioning, we are just modifying the existing schema. + +Let’s understand by an example. +We have a schema named user, which had fields such as id, firstName and lastName. +```graphql +type User { + id: Int! + firstName: String! + lastName: String! +} +``` + +In the above schema all fields are required. But in the next version we can add a variable and can also change the requirements. Such as : +```graphql +type User { + id: Int! + firstName: String! + middleName: String! + lastName: String! +} +``` + +Here we have added the `middleName` field which is 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. + + +### 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. + +### Evolution of Schema +This is definitely different from versioning, but this will be helpful to build schemas which can be evolved with time without making breaking changes. Schema can be evolved by making changes such as adding/removing fields, structures, types, etc. While making these changes, there can be some points which will restrict the schema while evolving and then @deprecated needs to be used as a last resort. For example there is a schema : +```graphql +type User{ + id: String! + name: String! + Username: String! + birthDate: DateTime! + lastLoginHistory: [DateTime]! +} + +``` +In the above schema we have one field named lastLoginHistory which stores the DateTime fields as a list. Now there needs some changes in the schema and some additional data needs to be added in lastLoginHistory. For that we need to add another field to the User schema. These changes will add many fields and this could make the schema lengthier and worse. + +But rather than this, we can build a schema for storing lastLoginHistory data and we can use that schema referenced to the User schema. +```graphql +type NewDateTime: { + lastLoginTime: DateTime! + lastLoginPeriodLength: Time! +} +``` +``` graphql +type User{ + id: String! + name: String! + Username: String! + birthDate: DateTime! + lastLoginHistory: NewDateTime! +} +``` +This way schemas can be evolved and can be maintained in a better way. Non-required fields should be deprecated but also the new fields should be introduced in that period and the old fields should be removed in such a way that no breaking changes occur. + + +### Example of Shopify +Shopify versioned their GraphQL APIs using the url versioning approach and made their graphql endpoint such as “/api/{ version }/graphql.json”. [Here](https://shopify.dev/concepts/about-apis/versioning#the-api-version-release-schedule) is the document of shopify. They deprecate the fields and instead name the new variable as newVariablev2. + +### Some tools for managing schemas +There are some tools which are used for schema validation, tracking schema versions, identifying unused types and many more. Some of the tools are `Apollo Graph Manager` and `GraphQL Inspector`. Schema can be validated using these tools and you can track all the schema changes. + +Using [Apollo Graph Manager](https://www.apollographql.com/docs/graph-manager/), you will be able to validate the schema and get the changes done in schema. For example : you will get to know which field is deprecated, for what reason and which fields are added new, etc. You will be able to validate the schema and check if anything is breaking or not. And you will also be able to know some detailed schema changes provided by this tool. +Apollo schema registry can track the changes of the schema and also gives the option to create variants of the schema. Also you can trace your GraphQL server by getting the report of which operations are being executed, which clients are executing which operations, which parts of schema are most used and which of the resolvers are used most. + +Now let’s have a look at GraphQL Inspector which also provides some similar functionalities. + +Using [GraphQL Inspector](https://graphql-inspector.com/), you can detect the changes which can be breaking changes for the current schema. You are able to know the restriction changes in fields as well as addition/subtraction in fields. A complete difference is provided between old schema and new schema. And by that you can get to know the differences in form of non-breaking change, dangerous change and breaking change. +In addition you can get the idea of coverage of the schema and can track which part of the schema is used, and by how many times. If any of the fields are deprecated, then the usage of those fields as well as checking of errors can be done using GraphQL Inspector. + +### Conclusion +By this way we can version the GraphQL APIs and just move to the game of managing fields instead of versioning. It’s as simple as if you don’t want any field, then just drop it and add necessary fields with appropriate roles.