How to really solve version problem

[CatTail]

Graphql do solve version problem by allow server add field dynamically without client changing their endpoint.

That's great, however, with an existing backend with versioning api, which is a proper way to support version change.

For example, with exist versioning backend api

endpoint: /api/v1/foo
response:

{
    "key": "value"
}

endpoint: /api/v2/foo
response:

{
    "key": [
        "value1",
        "value",
    ],
    "additional": "wow"
}

There are two problem,

1. Given an frontend app1, currently use api /api/v1/foo, how to setup a graphql server allow app1's future requirement to "additional" data (and use the old version of "key")?
2. Given another frontend app2, use api /api/v2/foo, is that possible to allow both app1 and app2 use the same graphql server without overhead (such as introduce versioning inside graphql server)?

[kevinSuttle]

See my conversation with @leebyron about versioning here: https://twitter.com/leeb/status/679045650575527936

[leebyron]

This is a good question @CatTail and one that comes up all the time.

We encourage GraphQL endpoints to take an add-only approach to schema evolution over time instead of changing existing fields. This is important for the preservation of behavior for existing clients without creating another dimension to implement on the server.

To be clear, this has its tradeoffs. You're exactly right that if you wanted to change your field "key" from returning one String to returning a List of Strings then this could potentially break your existing clients which are querying for the string. It means that instead you would have to pick a new field name to represent the new concept, maybe "keyList" or "keys" instead and leave the old one.

The addition of new fields is always safe for older clients. You can add your "additional" field without any ill effect since GraphQL queries always specify exactly what they want and nothing more. You can think of this as similar to what would happen if you added a new column in a SQL table. Existing queries could run against the same table without any issue and without any change to the result of their queries. The same concept applies for GraphQL.

Of course, there is nothing stopping you from changing a field's type in your GraphQL schema other than this concern. So for example, at Facebook, we often are developing new features and new applications which undergo rapid development and often require their GraphQL schema to change. However since no users are using them yet, we can safely cheat and change a field's type, knowing that we're only going to break our prototype builds for our internal developers. However once we've shipped a feature to our users, we do everything we can to avoid breaking it including not changing the GraphQL schema.