Changesets: Schema versioning and type overriding

[caspervk]

I would like to be able to make breaking changes to my GraphQL API. I am doing this by creating different schemas and exposing them at /graphql/v1, /graphql/v2 etc.

Most changes are relatively minor and implemented by subclassing the latest schema and overwriting a single mutator or changing a field. Earlier versions are implemented by subclassing the next version, leading to a chain of schemas all the way to the latest one. The latest schema is the "main" one, containing most of the logic, so that earlier versions can be deprecated and deleted. This isn't pretty, but it works. The code is open source, for example: https://github.com/magenta-aps/os2mo/blob/1f557a658145200e090c4805eb8fe24df6761bc1/backend/mora/graphapi/versions/v21/version.py.

Sometimes, subclassing the schema doesn't cut it. For example, if I need to change a field on a type which is used both directly in the top-level query as well as nested as fields on other types. In this case, I can overwrite the field and type on the top-level query easily, but I also have to overwrite in any fields which reference it, and then any fields which reference those models. The number of required changes quickly explodes.

Is there a better way to do this? Does the schema have a store of all types which I could use to overwrite one type with another everywhere in the schema at once?

---

EDIT: Subclassing is a bad idea. Please see my reply about GraphQL Ruby's Changesets.

[DoctorJohn]

From my experience, it's unusual in GraphQL to have the whole endpoint versioned. Instead, I recommend continuously updating a single schema. This is also mentioned on the GraphQL website:

common practice of always avoiding breaking changes and serving a versionless API.

Naturally, adding new types or fields is a non-breaking change in GraphQL. To deprecate old fields/types, you can use the @deprecated directive. If you have to change your schema in a breaking way, you could start versioning on a type or field level.

Have you considered this approach, or is versioning the endpoint the only option in your case?

[caspervk]

Thank you for taking the time to write such a thorough reply!

I found this talk by Shopify which explains their versioning scheme: https://gitnation.com/contents/hard-graphql-problems-at-shopify. Of particular interest is the Handling Deprecated Fields and Nullability and Nullability and Shopify's Versioning System sections:

Around the V2 and V3 naming things, that was because of a limitation that we had in our versioning of process, that is now fixed. So hopefully those will never happen again, because frankly they're ugly and they're very confusing. Like which do I use? Price V2, V3, but I'm using the January release of the schema, but I'm using V2, it's just a mess, right? We all love to have nice APIs that are named nicely and are very OCD about things being consistent. So dropping V2s and V3s are something we definitely wanna do.

you have to follow through on the process of like make a v2 field, get all your clients onto that v2 field, then get rid of your old field or change your old field and then migrate them back to the original field, right? So I think it's like always a long process to get rid of those v2 v3s in your code base.

basically we're making our versioning system that much more powerful to allow us to make these breaking changes in a nicer, more fluid way. That author v2 would not have to be a thing. It would literally just, if you request version A, it's not a null, you request version B in the future, it's suddenly null.

We're a little bit lucky because of the GraphQL Ruby Gen that we have supports a lot of things that we utilize to do versioning.

The feature he is referring to here is GraphQL Ruby's Changesets:

Out-of-the-box, GraphQL is versionless by design. GraphQL’s openness to extension paves the way for continuously expanding and improving an API. You can always add new fields, new arguments, and new types to implement new features and customize existing behavior.

However, sometimes a business case may call for a different versioning scheme. GraphQL-Enterprise’s “Changesets” enable schemas to release any change – even breaking changes – to clients, depending on what version of the schema they’re using. With Changesets, you can redefine existing fields, define new types using old names, add or remove enum values – anything, really – while maintaining compatibility for existing clients.

Changesets are a complementary evolution technique to continuous additions. In general, additive changes (new fields, new arguments, new types) are best added right to the existing schema. But if you need to remove something from the schema or redefine existing parts of the schema in non-backwards-compatible ways, Changesets provide a handy way of doing so.

From https://graphql-ruby.org/changesets/definition.html:

New things can be published in a changeset by adding added_in: SomeChangeset to their configuration. For example, to add a new argument to a field:

field :search_recipes, [Types::Recipe] do
  argument :query, String
  argument :tags, [Types::RecipeTag], required: false, added_in: Changesets::AddRecipeTags
end

You can also provide a replacement implementation by using added_in:. When a new definition has the same name as an existing definition, it implicitly replaces the previous definition in new versions of the API. For example:

field :rating, Integer, "A 1-5 score for this recipe" # This definition will be superseded by the following one
field :rating, Float, "A 1.0-5.0 score for this recipe", added_in: Changesets::FloatingPointRatings

Here, a new implementation for rating will be used when clients requests an API version that includes Changesets::FloatingPointRatings. (If the client requests a version before that changeset, then the preceding implementation would be used instead.)

A lot of other interesting examples are available at https://graphql-ruby.org/changesets/definition.html#examples:

Fields: adding, modifying, and removing fields
Arguments: adding, modifying, and removing arguments
Enum values: adding, modifying, and removing arguments
Unions: adding or removing object types from a union
Interfaces: adding or removing interface implementations from object types
Types: changing one type definition for another
Runtime: choosing a behavior at runtime based on the current request and changeset

---

I understand that schema versioning by inheritance is currently out of scope for the Strawberry project, but is there a way I could implement something similar to Ruby GraphQL's changesets in my Strawberry application?

[caspervk]

@erikwrede would a versioning scheme based on changesets also be out of scope of the project, or should I perhaps open a feature request?

[jirikuncar]

The following works for our use case.

@strawberry.type
class Query:
   v1: QueryV1
   v2: QueryV2

You still get a huge schema but you can reuse types that haven't changed between versions.

[caspervk]

Ideally I would like to avoid duplication and reuse as much code as possible between the versions. I'm not sure if the scheme you are suggesting enables this. Like in my original post, changing just one field can quickly explode when you have to overwrite it in any field which reference it, and then any field which reference those fields and so on.

I feel like GraphQL Ruby's Changesets was a true revelation -- I just don't know how to implement it in Strawberry.

[Skeen]

@jirikuncar The approach you're suggesting also does not work for mutations, which per Section 6.2.2 og the October 2021 GraphQL spec should be executed serially. Nesting mutations under a top-level version type breaks this seriality, and thus breaks mutation behavior.

If graphql/graphql-spec#252 was to be merged (unlikely seeing at it is ~8 years old at this point), this would change the behavior and make your suggested approach feasible for mutations, but as it stands now, the GraphQL spec does not support it.