API Versioning for GraphQL-Ruby

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.

Why Changesets?

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.

For example, if you add a values to an Enum, you can just add it to the existing schema:

  class Types::RecipeTag < Types::BaseEnum
    value "LOW_FAT"
    value "LOW_CARB"
+   value "VEGAN"
+   value "KETO"
+   value "GRAPEFRUIT_DIET"
  end

However, if you want to change the schema in ways that would break previous queries, you can do that with a Changeset:

class Types::RecipeTag < Types::BaseEnum
  # Turns out this makes you sick:
  value "GRAPEFRUIT_DIET", removed_in: Changesets::RemoveLegacyDiets
end

Then, only clients requesting API versions before this changeset would be able to use GRAPEFRUIT_DIET; clients requesting newer versions could not send it as input and would not receive it in responses.

(Changesets also support additive changes, if you prefer to make them that way.)

Getting Started

To start using Changesets, read on:

• Installing Changesets
• Writing Changesets
• Releasing Changesets